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Preface 



The main purpose of this publication is to 
explain, in general terms, the way in which 
programs compiled by the OS PL/I Optimizing 
Compiler (Program Number 573U-PL1) are 
executed. It describes the organization of 
object programs produced by the compiler, 
the contents of the load module, and the 
main storage situation throughout 
execution. The information provided is 
intended primarily for those involved in 
maintenance of the compiler and its related 
library program products. The publication 
will also provide valuable information for 
applications programmers, since a knowledge 
of the way in which source program 
statements are executed will lead to the 
writing of more efficient programs. The 
book also contains a chapter on how to 
obtain and read a PL/I dump. 



Although different source programs 
produce different executable programs, the 
structure of every executable program 
produced by the compiler is basically the 
same. This structure is explained in 
chapter 1. Chapters 2,3,4, and 5 describe 
the various elements that make up the load 
module, chapters 6 and 7 explain the 
housekeeping and error-handling schemes. 
Chapters 8, 9, 10, and 11 describe the 
implementation of various language 
features, the majority of which are handled 
by a combination of compiled code, PL/I 
library routines, and Operating System 
routines. chapter 12 is the guide to 
obtaining and using dumps. Chapter 13 
deals with interlanguage communication. 
The final chapter, chapter 14, discusses 
those aspects of execution that apply only 
to a multitasking environment. In 
addition, appendix A contains details of 
all control blocks that can exist during 
execution. 
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Processing a PL/I Program 



Figure 1. 1 shows the processes through 
which a PL/I program passes from its 
inception to its use. There are four 
stages: 

1. Writing the program and preparing it 
for the computer. 

2. Compilation: translating the program 
into machine instructions (i.e., 
creating an object module) . 

3. Link-editing: producing a load module 
from the object module. This includes 
linking the compiled code with PL/I 
library modules, and possibly with 
other compiled programs. It also 
includes resolving addresses within 
the code. 

4. Execution: running the load module. 

The process is not necessarily continuous. 
The program may, for example, be kept in a 
compiled or link-edited form before it is 
executedf and it will normally be executed 
a number of times once compiled. 



COMPILATION 



Compilation is the process of translating a 
PL/I program into machine instructions. 
This is done by associating PL/I variables 
with addresses in storage and translating 
executable PL/I statements into a series of 
machine instructions. For example, the 
PL/ I statements: 

DCL I,J,K; 
I=J*K; 

would typically result in the generation of 
machine instructions corresponding to the 
assembler language instructions shown 
below: 



LH 7,88(0,13) 
AH 7,90(0,13) 
STH 7,96(0,13) 



Load J into register 7 

Add K to J 

Place result in I 



the necessary machine instructions. 
Instead, certain statements are translated 
into calls to standard subroutines held in 
the OS PL/I Resident Library. some of the 
resident library routines may, in turn, 
call further library routines from either 
the resident or the transient PL/I library. 
The following PL/I statements would, for 
example, result in a call being made to a 
resident library routine. 

DCL X,Y; 
X=SIN(Y) ; 

The code that would typically result from 
such statements is shown below: 

LA 14,92(0,13) Place address of Y 

in register 14 

LA 15,96(0,13) Place address of X 

in register 15 

STM 14,15,80(0,3) Place addresses in 

argument list 

LA 1,80(0,3) Point register 1 at 

argument list 

L 15,88(0,3) Load register 15 

with the address of 
the resident library 
routine IBMBMGS. 
(This is held in the 
form of an address 
constant generated 
by the compiler and 
resolved by the 
linkage editor.) 

BALR 14,15 Branch to the 

library routine, 
which will carry out 
the required 
function. 



LINK-EDITING 



Link-editing links the compiler output with 
external modules that have been requested 
by the compiled program. These will be 
PL/I resident library routines, and, 
possibly, modules produced by further 
compilations. As well. as linking the 
external modules, the linkage editor also 
resolves addresses within the object 
module. 



(The variables I, J, and K are held at 
offsets 96,88, and 90, respectively, from 
the address in register 13.) 

The OS PL/I Optimizing Compiler does not 
translate all PL/I statements directly into 



EXECUTION 



The optimizing compiler produces code that 
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storage area 
[ISA) is acquired 



The program management 
area (a PL/I communications 
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allocated at the high 
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® When non- LIFO 
storage is freed, 
it is, where possible 
absorbed into the 
major free area. Where 
this is not possible, it 
is placed on a chain of 
free storage. The head 
of this chain is held at 
a fixed offset in the 
program management 
area. Areas on this 
chain are reused where 
possible. 



Figure 1.2. Use of PL/I dynamic storage 



requires a special arrangement of control 
blocks and registers for correct execution. 
This arrangement of control blocks and 
registers is known as the PL/ 1 .environment. 
Execution consequently becomes a three- 
stage process: 

1. Setting-up the environment. This is 
handled by the PL/I initialization 
routines IBMBPIR and IBMBPII. 

2. Executing the program. 

3. Completing jobs after execution. This 
consists of closing any files that are 
left open and returning control either 
to the supervisor or to a calling 
module. It is handled by a return to 
the initialization routine which calls 
a termination routine. 



Factors Affecting Implementation 



Three major factors influence the design of 
the executable programs produced by the 
optimizing compiler. These factors are 
inherent in the language, and are: 

^ • Th e jno,dular._structure _of , PL/I programs 

The PL/I language allows the 
programmer to divide his program into 
a series of blocks that can be written 
and compiled independently of each 
other. 

2. The dynamic allocation and freeing of 
storage 

Automatic, controlled, and based 
variables all have their storage 
allocated and freed dynamically. This 
implies a system of re-use of storage 
to reduce space requirements. 

3. The comprehensive facilities offered 
^ the PL/I language 

The PL/I language offers more 
facilities than any other high-level 
language. These facilities include 
allowing the PL/I program to control 
the flow of execution after any PL/I 
interrupt. 



Key Features of the Executable Program 



Taken together, the factors outlined above 
are responsible for the main features of 
the executable program produced by the 
compiler. These features are: 



1. 



2. 



A communications area addressed by a 
dedicated register throughout the 
execution of the program. 

A scheme to handle dynamic storage 
allocation. 

The use of standard subroutines from 
the PL/I libraries, to handle such 
standard tasks as the housekeeping 
scheme and error handling. 



4. 



All 



The use of initialization routines to 
set up the communications area and 
initiate the housekeeping scheme. 
PL/I modules are compiled on the 
assumption that the initialization 
routines have been called before they 
are entered. 

The issuing, by the initialization 
routines, of SPIE and STAE macro 
instructions to trap interrupts and 
ABENDS, and allow them to be handled 
as defined by PL/I. 



These features are discussed further below. 



COMMUNICATIONS AREA 



The facilities offered by the PL/I 
language, particularly the error-handling 
facilities, imply that certain items must 
be accessible at all times during 
execution. To simplify accessing such 
items, a standard communications area is 
set up for the duration of execution. This 
area is known as the task communications 
area (TCA) , and is addressed by register 12 
throughout execution. 



DYNAMIC STORAGE ALLOCATION 



The principles of the dynamic storage 
schem.e are illustrated in figure 1.2. 

The allocation and freeing of automatic 
storage on a block-by-block basis implies 
an automatic facility for the re-use of 
such storage. This problem and the problem 
of inter-block communication are solved by 
having, for each block, a save area that 
contains register save information, 
automatic variables, and housekeeping 
information. This area is known as a 
dynamic storage area (DSA) . It conaists of 
the standard operating system save area 
concatenated with certain housekeeping 
information and with storage for automatic 
variables. DSAs are held contiguously in a 
last-in/first-out (LIFO) storage stack and 
are freed and allocated by the alteration 
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Storage for any constants 
used in the program 
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internal 
control 
section 
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Control blocks and 

other data for 

external files, etc. 



Figure 1.3. Contents of a typical load module 



of pointer values. 

On entry to a block, the registers of 
the preceding block are stored in the 
previous DSA and a new DSA is acquired. A 
chainback pointer to the previous DSA is 
placed in the new DSA. This arrangement 
allows access to information in previous 
blocks. Register 13 is pointed at the head 
of the DSA for the current block. The code 
that carries out this and any other block 
initialization is known as prologue code. 
To obviate the need for special coding in 
the main procedure, a dummy DSA is set up 
by an initialization routine, and register 
13 points at this dummy DSA on entry to the 
main procedure. 

In addition to automatic variables, 
certain other types of storage are 
allocated and freed dynamically. Such items 
as are not freed on a last-in/ first-out 
basis are kept in a second stack. If items 
within this stack are freed, they are 
placed on a free-area chain. The storage 
scheme is handled partly by compiled code 
and partly by a resident-library routine. 
Compiled code acquires and frees space in 
the LIFO storage stack. 

The library routine IBMBPGR is called 
when non-LIFO dynamic storage has to be 
allocated or freed, or when there is 
insufficient space for an allocation of 
storage in the LIFO stack. 



combine fast execution with reduced space 
overheads. 



INITIALIZATION/TERMINATION ROUTINES 



The job of the initialization routines is 
to prepare a standard environment for all 
procedures compiled by the OS PL/I 
Optimizing Compiler. This consists of 
setting-up the TCA and initializing the 
storage scheme. A SPIE macro instruction is 
issued so that all program checks will be 
intercepted by the PL/I error-handling 
facilities. A STAE macro instruction is 
issued to trap ABENDS. On completion of the 
main procedure control is returned to the 
initialization routine by the epilogue code 
of the main procedure. The program is 
terminated under the control of the 
initialization routine. Using standard 
library routines for these tasks reduces 
the amount of special-case coding that is 
needed for a main procedure. A consequence 
is that subroutines can be compiled and 
tested individually and then joined with 
other procedures and run without 
recompilation. If this is done, care must 
be taken that the main procedure is the 
first passed to the linkage editor. 

Note : Use of the linkage editor ENTRY 
statement will not have the desired results 
as the program must be entered via the 
initialization routine. 



USE OF LIBRARY SUBROUTINES 



The use of library subroutines simplifies 
compilation. On the other hand, using such 
routines slows execution because they 
cannot be tailored for the particular * 
situation in hand, and because they incur 
the overhead of saving and restoring 
registers. Library subroutines are used 
for handling standard jobs such as program 
initialization and error handling, and for 
those items that require interpretive code. 
Interpretive code is required when a 
significant part of the data will not be 
available until execution. 

Two PL/I libraries are used by the OS 
PL/I Optimizing Compiler: the OS PL/I 
Resident Library and the OS PL/I Transient 
Library. Transient library routines have 
the advantage of saving space, because they 
require storage only when they are actually 
in use. Resident library routines, however, 
have the advantage of speed, because they 
do not have to be loaded during execution 
of the PL/I program. Dividing subroutines 
into transient and resident types enables 
the compiler to balance the advantages of 
both types and so to produce programs that 



Contents of a Typical Load Module 



The contents of a typical load module are 
shown in figure 1.3. The contents are: 

1., Compiled code (the executable machine 
instructions that have been 
generated) . 

2. Link-edited routines. These will 

include resident library routines and 
probably OS data management routines. 
Certain resident library routines are 
included in every executable program 
phase. These are the initialization 
routine, IBMBPIR, and the error 
handler, IBMBERR. Other resident 
routines are included as required. 

As well as executable machine 
instructions, the program requires certain 
control information and addresses. Some of 
these are listed in figure 1.3, but full 
details are given in chapter 2. The figure 
also shows PLISTART, which passes control 
to the initialization routine, and PLIMAIN, 
which holds the address of the start of 
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Figure I.H.. Use of storage 
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Receives control from 
system 



Initialization routines 



Set up TCA, initialize storage and 
issue SPIE & STAE to initialize 
PL/I error-liandling scheme. Pass 
control to the address in 
PLIMAIN. 



Prologue code 



Acquires DSA for main 
procedure. Initializes 
control blocks, etc. 



Functional code 



Carries out function required 
In source program. This 
usually involves calls to 
library subroutines. 
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registers 
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Closes any files still open and 
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Figure 1.5. Flow of control during execution 
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compiled code. 



The Ovesrall Use of Storage 



procedure compiled code, with register 
12 pointing at the TCA and register 13 
pointing at the dummy pSA. The 
address to which IBMBPIR passes 
control is held in the control section 
PLIMAIN. 



The overall use of storage is illustrated 
in figure I.4. As can be seen, an area 
known as the initial st orage area (ISA) is 
acquired for program management and PL/I 
dynamic storage. The program management 
area is set up by the initialization 
routines, and includes the TCA and the 
dummy DSA discussed above. The remainder 
of the ISA is used for PL/I dynamic storage 
allocations. The LIFO stack starts beyond 
the end of the program management area and 
expands, as necessary, towards the end of 
the ISA. Non-LIFO dynamic storage starts 
at the end of the ISA and expands towards 
the LIFO stack. Storage for I/O buffers and 
transient library routines is acquired by 
issuing GETMAIN macro instructions. 



4. Compiled code prologue stores the 
contents of the registers used by 
IBMBPIR in the dummy DSA and acquires 
a DSA for the main procedure. 

5. Compiled code calls the library 
routines used for stream I/O. These 
in turn call transient routines to 
open the standard files and further 
transient routines to interface with 
data management routines. 

6. Processing is then carried out by 
compiled code. Further calls to the 
library may be involved if, for 
example, mathematical functions are 
used. 



The Process of Execution 



The stream output will involve further 
steps similar to those described in 5, 
above. 



The process of execution is illustrated in 
figure 1. ;>. The processes involved for a 
sample program are described below. 

SAMPLE: PROC OPTIONS (MAIN) ; 
INPUT: GET LIST (Y,Z); 



(process data as required) 



PUT LIST(X) ; 

IF X<500 THEN GO TO INPUT; 

END; 

During execution: 

1. The control program passes control to 
the control section PLISTART, which 
has been generated by the compiler. 

2. PLISTART calls the resident library 
initialization routine, IBMBPIR. 

3. IBMBPIR and IBMBPII (called by IBMBPIR) 
set up the PL/I environment. IBMBPIR 
then passes control to the main 



8. When the END statement is reached, the 
epilogue code is entered. This 
restores the registers of IBMBPIR, the 
initialization routine, and returns 
control to IBMBPIR. 

9. IBMBPIR raises the FINISH condition, 
calling the resident error-handling 
module IBMBERR, which searches for a 
FINISH on-unit. Finding none, it calls 
IBMBPIT. IBMBPIT carries out certain 
housekeeping tasks, including calling 
IBMBOCL to close the files that have 
been opened. IBMBPIT returns control 
to IBMBPIR, which returns control to 
the supervisor. 

This program illustrates the main points 
mentioned earlier in the chapter. The 
initializationroutines are used in steps 3 
and 9, to set up and discard the PL/I 
environment. The storage management scheme 
is illustrated in the prologue and epilogue 
code in steps 4 and 8. The communications 
area (TCA) is set up by the initialization 
routine, and the use of standard library 
subroutines is shown in steps 5 and 7 . The 
use of special error and_PL/I_ c ondition 
handling code is shown in step 9. 



Program control section 



COMPILER 



Housekeeping 
control sections 
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Instructions passing control to 

initialization routine 



PLIMAIN 
Contains: 

Address of main procedure 



, PL I FLOW 
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I External reference to library 
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subroutines 
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Executable instructions 
translated from source 
program 




Static internal control section 



Contains: 
Addresses 
Constants 

Control information 
Static internal 
variables 



Control sections for 
data declared 
EXTERNAL 



A separate control section for each 
external: 

Variable 

File 

Procedure 

User condition 

Symbol table for external data 



_l 



Dummy Section 



A control section for each 
compiler-generated subroutine 
used in a program 



L 



Control sections surrounded with dotted lines are generated only when required. 



1 
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information for 
files and controlled 
variables. 

Becomes the 
pseudo-register 
vector (PRV). 



Figure 2.1. The output from the compiler 
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Chapter 2: Compiler Output 



Introduction 



This chapter describes that part of the 
load module that is generated by the 
compiler. The compiler output is a 
relocatable object module consisting of a 
series of records in card-image format. 
These records contain either machine 
instructions, constants, or external or 
internal addresses to be resolved by the 
linkage editor. The records are known as: 



TXT records - records containing 

machine instructions or constants. 

RLD records - records containing 
internal addresses. 

ESD records - records containing 
external addresses. 



Further information about the output passed 
to the linkage editor is given in the 
publication .QS..,gL/I_Qptimi2ing Compiler; 
Program Logic . 

There are two main control sections 
output by the compiler. These are: 

1. The program control section, holding 
the executable instructions translated 
from the PL/I program. 

2. The static internal control section 
holding constants, addresses, and 
static variables. 

A number of other control sections are also 
generated. These either handle certain 
housekeeping functions, or are used for 
external data which may have identical 
control sections generated for it by other 
compilations. 

Workspace and storage for automatic 
variables is acquired during execution, 
normally by the prologue code that is 
executed at the start of every block. 

The output from the compiler is shown in 
figure 2.1 and listed below: 

1. Control sections that are always 
generated 



Static internal 
control section 



PLI START 



Containing 
addresses, control 
blocks, constants, 
and STATIC INTERNAL 
variables. 

The entry point for 
the executable 
program phase. 
Passes control to 
initialization 
routine. 



Control sections that are generated 
2SiY 3*h§S required 

PLIMAIN Containing the 

address of the entry 
point of the main 
procedure. 
(Generated only for 
procedures with 
OPTIONS (MAIN). ) 

PLIFLOW A control section 

generated when the 
compiler FLOW option 
is specified. (See 
chapter 7 . ) 

PLICOUNT A control section 
generated when the 
COUNT compiler 
option is specified. 

Static external A static external 
control sections control section is 
generated for every 
external variable, 
file, and procedure. 



3. 



Plus control 
sections for 



sections 



Pseudo-register 
vector 



Each user-defined 
condition, and each 
compiler-generated 
subroutine used. 



A dummy section used 
in addressing files 
and controlled 
variables. 



Program control 
section 



Containing 
executable 
instructions. 



The remainder of this chapter deals with 
these items in further detail. Where 
possible, it refers to the object program 
listing, because this is the form in which 
the output from the compiler is most 
readily accessible. 

The two control sections, PLISTART and 
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Name 


Contents 


Compiler Option 


1 


Source program 


Source program statements 


SOURCE 




Aggregate table 


Names and storage requirements of structures 
and arrays 


AGGREGATE 




Storage requirements 


Names and storage requirements of all 
procedures 


STORAGE 




ESD references 


Name, type, and identifier of all external 
references generated by the compiler* 


ESD 




Statistics 


Number of source records, program text 
statements, and object code bytes 


ESD 




Static storage 


Contents of static internal and static 
external control sections in hexadecimal 
notation with comments 


MAP 




Table of offset and 
statement number 


Offsets, within code, of the start of each 
statement 


OFFSET 




Object program 


The contents of the program control section 
in hexadecimal and translated into a 
pseudo-assembler-language format 


LIST 




Variables offset 
MAP 


The offsets of automatic and static internal 
variables from their defining base 


MAP 




* External references within library modules are not included. 







L :J 



Figure 2., 2. Contents of listing and associated compiler options 



PLIMAIN, are used during program 
initialization. PLISTART holds the address 
of the library initialization routine 
IBMBPIR, which will be entered at the start 
of the program. PLIMAIN holds the address 
of the start of the code for the main 
procedure'. This is the address to which 
the library initialization routine branches 
when initialization is complete; it is 
marked "♦REAL ENTRY" in the object-program 
listing. 

A PLIMAIN control section is generated 
for every procedure for which OPTIONS 
(MAIN) is specified in the procedure 
statement. When two such procedures are 
being run together, control will pass to 
the first of the procedures processed by 
the linkage editor (unless the program's 
JCL specifically indicates otherwise). 

The format of PLIMAIN and PLISTART is 
given in appendix A. 

If the compiler FLOW option is being 
used, a control section called PLIFLOW is 
also generated. This contains code that 
results in the link-editing of the trace 
module IBMBEFL and also contains the values 
of "n" and "m" specified in the option. 



The format of PLIFLOW is given in chapter 
7. 



Thg Organization of this Chapter 



The remainder of this chapter describes the 
contents of the static internal control 
section and the program control section. 
First the conventions used in the object 
program listing and the static storage map 
are described. Descriptions of the two 
control sections follow. The description 
of the program control section covers the 
conventions used in the object program code 
such as register usage, method of handling 
flow of control, and addressing 
information. The chapter is completed by a 
short discussion of the effects of 
optimization. 



Listing Conventions 



Figure 2.2 shows all the program listing 
information that can be produced by the 
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SOURCE 


1 

2 


1 




EXAMPLE: 


PROC OPTIONS (MAIN) REORDER; 
DCL X(10),Y,Z INITIAL (0); 


3 


1 






GET EDIT(X,Y) (F(3),X(11)); 


U 
5 
6 
7 
8 


1 
1 
1 
1 
1 


1 
1 




DO 1=1 TO Y; 
Z=Z*X(I); 

END; 
PUT EDIT(Z) (A) ; 
END; 



STATIC INTERNAL STORAGE MAP 



STATIC EXTERNAL CSECTS 



000000 00000008 

000004 0000005E 

000008 00000068 

OOOOOC 00000000 

000010 00000000 

00001U 00000000 

000018 00000000 

00001C 00000000 

000020 00000000 

000024 00000000 

000028 00000000 

00002C 00000000 

000030 00000000 

ooao3u 00000000 

000038 00000000 

00003C 00000000 

ooooao 00000000 

000044 00000000 

000048 00000000 

00004C 00000000 

000050 00000000 

000054 00000000 

000058 00000000 

00005C 00000000 

000060 08040680 

000064 500000030080 

00006A 6000000B 

00006E 5800000C 

000072 OOOA 

000074 0001 

000076 0004 

000078 91E091E0 

00007C 00000000 

000080 46008000 

000084 41100000 

000088 00000000 

00008C 00000000 

000090 00000000 

000094 80000000 

000098 00000000 

00009C 80000000 

OOOOAO 0000010400000068 



PROGRAM ADCON 

PROGRAM ADCON 

PROGRAM ADCON 

A. .lELCGIA 

A..IELCGIB 

A. .lELCGOA 

A. .lELCGOE 

A. .IBMBCACA 

A..IBMBCEDB 

A..IBMBCHFD 

A..IBMBCTHD 

A..IBMBCVDY 

A. .IBMBOCLA 

A. .IBMBOCLC 

A. .IBMBSACA 

A. .IBMBSEIA 

A. .IBMBSEIT 

A..IBMBSEOA 

A. .IBMBSFIA 

A. .IBMBSIIA 

A. .IBMBSICA 

A..IBMBSIOT 

A. .IBMBSXCA 

A. .STATIC 

DED. .X 

FED 

FED 

FED 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

A. .DCLCB 

A..DCLCB 

A. .DCLCB 

A . . TEMP 

A. .DCLCB 

A.. TEMP 

COMPILER LABEL CL.9 



000000 0000000000000000 
0000000000000000 
OF4700140005E2E8 
E2C9D520 



000000 FFFFFFFC41201000 
O2D7OFO0OO0000OO 
FF6000140008E2E8 
E2D7D9C9D5E3008B 



DCLCB 



ECLCE 



Figure 2.3. Example of static storage listing 
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PL/I OPTIMIZING COMPILER 



OOOOOtt 


91 


10 




ulO 


000008 


17 


10 




052 


OOOOOC 


58 


FO 




Oil 


000010 


50 


70 




01C 


00001U 


58 


•70 




OOC 


000018 


18 


EO 


F 


u50 


00001C 


IB 


EO 


7 


002 


000020 


10 


EO 


F 


050 


00002'* 


58 


EO 


F 


01C 


000028 


1A 


EO 


7 


002 


00002C 


50 


EO 


F 


01C 


000030 


18 


EO 


1 


020 


00003U 


11 


EO 


E 


001 


000038 


10 


EO 


1 


020 


00003C 


10 


EO 


F 


052 


000010 


91 


10 


1 


010 


ooooau 


07 


86 






0000146 


58 


70 


1 


oic 


00004A 


58 


FO 


7 


068 


OOOOUE 


05 


EF 






000050 


07 


F6 






000052 


58 


FO 


7 


06C 


000056 


05 


EF 






000058 


58 


EO 


1 


008 


00005C 


50 


EO 


D 


OIC 


000060 


91 


BF 


1 


010 


000061 


07 


F6 






000066 


07 


00 






000068 










00006C 











TK 


16(1) ,X'10' 


BO 


♦ + 71 


L 


15,20(0, 1) 


ST 


7,28(0, 1) 


L 


7, 12(0,1) 


LH 


11,80(0, 15) 


SH 


11,2(0,7) 


STH 


11,80(0,15) 


L 


11,76(0, 15) 


AH 


11,2(0,7) 


ST 


11,76(0, 15) 


LH 


11,32(0,1) 


LA 


11, 1(0, 11) 


STH 


11,32(0,1) 


STH 


11,82(0, 15) 


Ty 


16(1) ,X'10' 


BCR 


8,6 


L 


7,28(0,1) 


L 


15, 101(0,7) 


BALR 


11,15 


BR 


6 


L 


15,108(0,7) 


BAIR 


11, 15 


L 


11,8(0,1) 


ST 


11,76(0, 13) 


NI 


16(1) ,X'BF' 


BR 


6 


NOPR 





DC 


ALKO) 


DC 


ALKO) 



♦ END OF COMPILER GENERATED SUBROUTINE 



* STATEMENT NUMBER 

000000 

000007 



* PROCEDURE 



♦ REAL ENTRY 



000008 
OOOOOC 
000010 
000011 
000018 
00001C 
000020 



90 EC D OOC 
17 FO F Oil 
00000000 
00000130 
00000000 
58 30 F 010 
58 10 D OIC 



000021 


58 


00 


F 


OOC 


000028 


IE 


01 






00002A 


55 


00 


C 


OOC 


00002E 


17 


CO 


F 


030 


000032 


58 


FO 


C 


071 


000036 


05 


EF 






000038 


58 


EO 


D 


018 


00003C 


18 


FO 






00003E 


90 


EO 


1 


018 


000012 


50 


CO 


1 


001 


000016 


11 


01 





000 


00001A 


50 


50 


c 


058 


00001E 


92 


80 


D 


000 


000052 


92 


21 


C 


001 


000056 


D2 


03 


D 


051 


00005C 


05 


20 







3 078 



* PROLOGUE EASE 

* INITIALISATION CODE FOR Z 
00005E 78 10 3 07C 
000062 70 10 D OAC 
000066 05 20 

* PROCEDURE EASE 



NOPR 







♦ STATEMENT N( 


JKi 


3ER 


DC 


ALKO) 




000068 


11 


90 


C 


108 


DC 


ALKO) 




00006C 


50 


90 


3 


091 








000070 


96 


80 


3 


091 


ITINE 






000071 


92 


21 


D 


119 








000078 


11 


EO 


3 


OAO 








00007C 


50 


EO 


D 


120 








000080 


11 


10 


3 


090 


DC 


C EXAMPLE* 


000081 


58 


FO 


3 


OIC 


DC 


AL1 (7) 




000088 


05 


EF 












00008A 


11 


AO 


2 


06E 




EXAMPLE 


00008E 


18 


EO 


3 


071 








000092 


50 


EO 


D 


0E8 








000096 










STM 


11,12, 12(13) 


000096 


58 


90 


D 


0E8 


B 


♦ + 16 




00009A 


8E 


90 





002 


DC 


A (STMT. 


, NO. TABLE) 


00009E 


11 


E9 


D 


OBI 


DC 


F'301' 




0000A2 


11 


FO 


3 


060 


DC 


A(STATIC CSECT) 


O0OOA6 


11 


10 


D 


108 


L 


3,16(0, 


15) 


OOOOAA 


50 


10 


D 


OEC 


L 


1,76(0, 


13) 


OOOOAE 


90 


EF 


1 


008 



CI. 5 



L 


0, 12(0, 15) 


AIR 


0, 1 


CL 


0,12(0, 12) 


ENH 


+ + 10 


L 


15, 116(0, 12) 


EAIP 


11,15 


L 


11,72(0, 13) 


IR 


15,0 


STM 


11,0,72(1) 


ST 


13,1(0,1) 


lA 


13,0(1,0) 


ST 


5,88(0,13) 


yvi 


0(13), X"80' 


V.Vl 


1(13) ,X'21' 


KVC 


81(1, 13), 120(3) 


BALR 


2,0 



IE 1,121(0,3) 
STE 1,Z 
EALR 2,0 



LA 


9,261(0, 13) 


ST 


9, 118(0,3) 


CI 


118(3) ,X'80' 


MVI 


281(13) ,X'21' 


LA 


11,160(0,3) 


ST 


11,288(0, 13) 


lA 


1, 111(0,3) 


L 


15,A..IEMBSIIA 


EALR 


11, 15 


LA 


10,CL.8 


LH 


11,116(0,3) 


ST 


11,232(0, 13) 


EQU 


♦ 


L 


9,232(0, 13) 


SLA 


9,2 


LA 


11,VC. .X(9) 


LA 


15,EED..V0. .X 


lA 


1,261(0, 13) 


ST 


1,236(0, 13) 


STK 


11, 15,8(1) 
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0000B2 


05 


AA 






0000B1 


58 


EO 


D 


0E8 


000088 


1A 


EO 


3 


071 


OOOOBC 


50 


EO 


D 


UE8 


OOOOCO 


19 


EO 


3 


U72 


0000C1 


17 


CO 


2 


02E 


0000C8 


11 


EO 


D 


0A8 


oooocc 


50 


EO 


1 


008 


OOOODO 


05 


AA 






0000D2 


17 


FO 


2 


9C 


0000D6 










0000D6 


11 


EO 


3 


061 


OOOODA 


58 


10 


D 


OEC 


OOOODE 


58 


70 


3 


OOC 


0000E2 


05 


67 






0000E1 


58 


FO 


3 


018 


0000E8 


05 


EF 






OOOOEA 


58 


70 


3 


UlO 


OOOOEE 


05 


67 






OOOOFO 


05 


AA 






0000F2 


11 


EO 


3 


06; 


0000F6 


58 


10 


D 


OEC 


OOOOFA 


58 


70 


3 


OOC 


OOOOFE 


05 


67 






000100 


17 


FO 


2 


06E 


000101 











CL.8 



CL.9 



BALR 


10,10 


L 


11,232(0, 13) 


AH 


11,116(0,3) 


ST 


11,232(0, 13) 


CH 


11,111(0,3) 


BNH 


CL.5 


LA 


11, Y 


ST 


11,8(0,1) 


BALR 


10, 10 


B 


CL.9 


EQU 


♦ 


LA 


11,100(0,3) 


L 


1,236(0, 13) 


L 


7,A..IELCGIA 


BALR 


6,7 


L 


15,A..IBMBSFIA 


BALR 


11,15 


L 


7,A..IELCGIB 


BALR 


6,7 


BALR 


10,10 


LA 


11,106(0,3) 


L 


1,236(0, 13) 


L 


7,A..IELCGIA 


BALR 


6,7 


B 


CL.8 


EQU 


* 



00013E 50 EO D 0F8 



ST 



11,218(0,13) 



♦ CALCULATION OF CCMMONED EXPRESSION FOLLOWS 
000112 78 20 C OFI LE 2,211(0,13) 
000116 70 20 D OFC STE 2,252(0,13) 

* END OF CO^?MON CODE 

+ CONTINUATION OF STATEMENT NUKEER 1 
00011A CL.2 EQU ♦ 



♦ STATEMENT NUMBER 5 
00011A 58 70 C 0F8 
00011E 78 10 D OAC 
000152 7C 17 D 0E1 
000156 70 10 D OAC 



L 7,218(0,13) 

IE 1,Z 

KE 1,VC..X(7) 

STE 1,Z 



♦ STATEMENT NUMBER 6 

♦ METHOD OR ORDER OF CALCULATING EXPRESSIONS CHANGED 

♦ CODE MOVED FROM STATEMENT NUMBER 1 

00015A 78 00 C OFC LE 0,252(0,13) 

00015E 7A 00 3 081 AE 0,132(0,3) 

000162 70 00 C OFC STE 0,252(0,13) 



Figure 2.4. Part of an object program listing (For source see Figure 2.3) 



in 



compiler. It also shows the relevant 
compiler options and sumitiarizes the 
information that will be produced if these 
options are specified. Some or all of 
these options may be deleted at system 
generation time. To obtain deleted 
options, the correct password (specified at 
system generation time) must be specified 
in the CONTROL option. 

This chapter describes the contents of 
the static-storage map and the object- 
program listing. Information on the other 
items generated is given in the publication 
OS PL/ 1 Optimizing Compiler: ggog;^amroer*.s 
Guide. 



STATIC-STORAGE- MAP 



The static-storage map is a formatted 
listing of the contents of the static 
internal and static external control 
sections. The static control sections 
contain items grouped in the following 
order: 

1. Address constants for entry points to 
procedures, and for branch 
instructions. 

2. Address constants for resident library 
subroutines . 

3. Address constants for addressing 
static storage beyond 4K. 

4. The constants pool, which contains 
source program constants, data element 
descriptors , locator/descriptors , 
symbol tables, declare control blocks 
(DCLCBs) , and other control blocks. 

5. static variables. 

The constants pool and the static-variable 
sections of static storage begin on 
doubleword boundaries. 

The static control section is listed, 
each line comprising the following 
elements: 

1. Six-digit hexadecimal offset. 

2. Hexadecimal text, in 8-byte sections 
where possible. 

3. Comment, indicating the type of item 
to which the text refers; a comment 
appears against only the first line of 
the text for an item. 

A typical static listing is shown in 
figure 2.3. 

The following comments are used (xxx 



indicates the presence of an identifier) : 

A.. - Address constant. 

COMPILER LABEL CL.nn - Compiler-generated 
label followed by CL plus number. 

CONDITION CSECT - Control section for 
programmer-named condition 

CONSTANT 

CSECT FOR EXTERNAL VARIABLE - Control 
section for external variable. 

D.. - Descriptor. 

DED.. - Data element descriptor. 

ENVB - Environment control block. 

DCLCB - Declare control block. 

FED.. - Format element descriptor. 

KD.. - Key descriptor. 

ONCB - ON control block. 

PICTURED DED.. - Pictured DED. 

RD.. - Record descriptor. 

SYMTAB - Symbol table. 

USER LABEL XXX - Source program label for 
xxx. 

xxx - Name of variable. If the variable is 
not initialized, no text appears 
against the comment; there is also no 
static offset if the variable is an 
array. (The static offset can be 
calculated from the array descriptor 
if required. ) 

OBJECT- PROGRAM LISTING 



By including the option LIST in the PROCESS 
statement, the programmer can obtain a 
listing of the compiled code, known as the 
object-program listing. This listing 
consists of the machine instructions plus a 
translation of these instructions into a 
form that resembles assembler language, and 
a number of comments such as the statement 
number. The format of this listing is shown 
in figure 2.4. As can be seen, blocks of 
code are headed by the number of the 
statement in the PL/I program to which they 
are equivalent, when optimization has 
resulted in code being moved out of a 
statement, this is indicated. Only 
executable statements appear in the 
listing. DECLARE statements are not 
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included, because they have no direct 
machine-code equivalent. To simplify 
understanding of the listing, the names of 
PL/I variables are inserted, rather than 
the addresses that appear in the machine 
code. Special mnemonics are used when 
referring to control blocks and other 
items . 

Statements in the object program listing 
are ordered by block. Statements in the 
outermost block are given first, followed 
by statements in the inner blocks. Thus 
the order of statements will frequently 
differ from that of the source program. 

Every object- program listing begins with 
the name of the procedure. The name is 
defined as a constant in a DC instruction. 
This is followed by another constant 
containing the length of the procedure 
name. Then comes the name of the 
procedure, as a comment, followed by code 
under the heading "REAL ENTRY." This is 
the point at which the code will, in fact, 
be entered. The second section of code is 
the prologue, which carries out various 
housekeeping tasks and is described more 
fully later in this chapter. The end of 
the prologue is marked by the message 
"PROCEDURE BASE. " This is followed by a 
translation of the first executable 
statement in the PL/I source program. 

The comments used in the listing are as 
follows: 

♦ PROCEDURE XXX - identifies the start of 
the procedure labeled xxx. 

♦ REAL ENTRY XXX - heads the 
initialization code for an entry point 
to a procedure labeled xxx. 

♦ PROLOGUE BASE - identifies the start of 
the prologue code common to all entry 
points into that procedure. 

♦ PROCEDURE BASE - identifies the address 
loaded into the base register for the 
procedure. 

♦ STATEMENT LABEL xxx - identifies the 
position of source program statement 
label xxx 

♦ PROGRAM ADDRESSABILITY. REGION BASE - 
identifies address to which the program 
base is updated if the program size 
exceeds 4096 bytes and consequently 
cannot be addressed from one base. 

♦ CONTINUATION OF PREVIOUS REGION - 
identifies the point at which addressing 
from the previous program base 
recommences. 

♦ END OF COMMON CODE - identifies the end 



of code used in the execution of more 
than one statement. 



END PROCEDURE xxx - identifies the end 
of the procedure labeled xxx. 

BEGIN BLOCK xxx - indicates the start of 
the begin block with label xxx. 

END BLOCK xxx - indicates the end of the 
begin block with label xxx. 

BEGIN BLOCK - GENERATED NAME BLOCK. nn - 
indicates the start of an unnamed begin 
block for which the compiler has 
generated the name BLOCK. nn, where nn is 
two hexadecimal digits. 

END BLOCK. nn - indicates the end of the 
begin block with compiler-generated name 
BLOCK. nn. 

STATEMENT NUMBER n - identifies the 
start of code generated for statement 
number n in the source listing. 

INTERLANGUAGE PROCEDURE xxx - identifies 
the start of encompassing procedure xxx 
(see chapter 13) . 

END INTERLANGUAGE PROCEDURE xxx - 
identifies the end of encompassing 
procedure xxx. (See chapter 13) 

COMPILER GENERATED SUBROUTINE xxx - 
indicates the start of compiler- 
generated subroutine xxx. 

END OF COMPILER GENERATED SUBROUTINE - 
indicates the end of the compiler- 
generated subroutine. 

ON UNIT BLOCK - indicates the start of 
an on- unit block. 

ON UNIT BLOCK END - indicates the end of 
the on-unit block. 

END PROGRAM - indicates the end of the 
external procedure. 

INITIALIZATION CODE FOR OPTIMIZED LOOP 
FOLLOWS - indicates that some of the 
code that follows has been moved from 
within a loop by the optimization 
process. 

CODE MOVED FROM STATEMENT NUMBER n - 
indicates object code moved by the 
optimization process to a different part 
of the program and gives the number of 
the statement from which it originated. 

CALCULATION OF COMMONED EXPRESSION 
FOLLOWS - indicates that an expression 
used more than once in the program is 
calculated at this point. 
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r ' T 

1 REGISTER USAGE (compiled code) | 


1 1 Dedicated | Work registers | Preferred registers | Notes | 
1 1 registers | (plus special use) | j | 


I 1 1 General | | Cannot be used | 

II 1 1 1 as base j 


II 1 of parameter list | | | 


1 2 1 Address of | | | Saved during | 

I 1 program base j j | in-line record | 

II 1 1 1 I/O and TRT | 


1 3 1 Address of | | | I 
1 1 static base | j j 1 


I 4 1 1 1 1 Address of | 

II 1 1 1 if DSA size 1 

I 1 1 I 1 greater than | 

II 1 1 1 38 96 bytes | 


I 5 1 1 General + static | Preferred register | | 

II 1 to procedure | control variable | | 


1 6 1 1 General | | j 


1 7 1 1 General | | I 


1 8 1 1 General | | | 


1 9 1 1 General | | j 


1 10 1 1 General | Preferred registers for | | 


1 11 1 1 General | BXLE instruction is used j j 


1 12 1 Address of TCA | | I I 


1 13 1 Address of | | | I 
1 1 current DSA j j | I 


1 lU 1 1 General + branch- | | I 


I 15 1 1 and other routines j I j 



Figure 2.5. Register usage in compiled code 



METHOD OR ORDER OF CALCULATING 
EXPRESSIONS CHANGED - indicates that the 
order of the code following has been 
changed to optimize the object code. 



In certain cases, mnemonics are used to 
identify the type of operand in an 
instruction, and, where applicable, this is 
followed by the name of a PL/I variable. 
The following prefixes are used: 



ADD.. 



BASE. . 



BLOCK. nn 



CL.nn 



A.. 



Address constant. 



Aggregate descriptor 
descriptor. 



Base address of a 
variable. 

Label created for an 
otherwise unlabeled 
block. 

Compiler-generated 
label. 
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D.. 
DED.. 

WSP.n 

L.. 

LOCATOR- 

RKD.. 

VO. . 



Descriptor. 

Data element 
descriptor. 

Workspace, followed by 
decimal number of the 
block of allocated 
workspace. 

Length of variable. 

Locator. 

Record or key 
descriptor. 

Virtual origin (the 
address where element 
would be held for a 
one- dimensional array, 
element 0,0 for a 
two-dimensional array, 
etc. ) . 



address vector 
Symbol tables 



Diagnostic 
statement table 



used in 

data-directed I/O. 
(See chapter 4.) 

Information on 
statement numbers. 



Static Internal Control Section 



Items are arranged according to their 
alignment requirements, those requiring 
doubleword alignment first, followed by 
fullword, half word, byte, and bit. 

The final section of the static internal 
control section holds the static variables. 
These are held in size order, smallest 
first, as for automatic variables: first 
the variables of 8 bytes or less, next the 
variables of 2018 bytes or less, and 
finally any variable greater than 2048 
bytes. This system ensures that the 
smallest possible number of items will 
require indirect addressing, since it will 
always be the largest variables that 
overflow the 4K boundary. Within each 
division, items are grouped according to 
alignment stringencies, starting with those 
requiring doubleword alignment. This 
method ensures optimum use of storage. 



The static internal control section 
contains the majority of items that are not 
executable instructions. The contents of a 
typical static control section are shown in 
figure 2«3. 

The first part of the static internal 
control section contains addresses. These 
are held in the order: 

1. Addresses of library modules 

2. Addresses of entry points 

3. Addresses of label constants that may 
be assigned to label variables 

4. Addresses of external procedures 
(other than library modules) 

The address section is followed by a 
section known as the constants pool . This 
contains the following items (if required 
by the program) : 



Constants 



ONCBej 



Descriptors, 
locators S 



constant values used 
by compiled code. 

Control blocks used 
in error handling. 
(See chapter 7.) 

Control information 
used by compiled 



DEDs (data element code and library, 
descriptors) (See chapter 4.) 



Symbol table 



Control information 



Program Control Section 



The program control section contains the 
executable instructions that are a 
translation of the PL/I source program. 
The format of each program control section 
depends on the contents of the source 
program. The discussion that follows 
covers items that will be common to all 
source programs. 

To keep discussions of subjects as 
complete as possible the chapter also 
includes descriptions of certain library 
functions when they are closely allied with 
the subject under discussion. 



REGISTER USAGE 



Details of register usage during the 
execution of compiled code are given in 
figure 2.5. 

Four general registers are used as bases 
for addressing various types of data; these 
are known as dedicated registers. The 
remainder of the registers are used as they 
are required and are known as work 
registers 

Dedicated registers are: 

R2 Program base. 
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R3 Static base. 



W2£}S_E§2isters 



R12 TCA pointer. 

Rl3 DSA pointer. 

This arrangement of dedicated registers 
allows compiled code the use of five 
even/ odd work register pairs. These are 
(0,1), (6,7), (8,9), (10,11), and (14,15). 

Certain registers have special tasks for 
which they are always used, or for which 
they are preferred and used when available. 
These tasks are shown in figure 2.5. 



Special or preferred uses for work 
registers are shown in figure 2.5. Special 
uses are those for which the register is 
freed and always used. Preferred uses are 
those for which the register is used when 
possible. 



I!i2^£iS9zP2iSJ&_5§2i§iers 



Floating-point registers are all used as 
general work registers for floating-point 
data. 



Deidicated__Registers 



Register 2 - Program, Base_ Register : 
Register 2 is the program base register and 
is used for branching within the code. 
When the code exceeds UK, register 2 is 
updated so that all branching is done on 
this register. During in-line I/O (when 
data management calls are handled by 
compiled code rather than by library 
subroutines), and during the execution of 
TRT instructions, the program base register 
contents are saved and the register used 
for other purposes. 

Register _3_2,..Static_Base Register : 
Register 3 points to the start of the 
static internal control section. The items 
to be found in this control section in any 
particular program are listed in the 
static-storage map put out by the compiler, 
(see "Static Internal control Section," 
later in this chapter.) When the static 
control section is larger than 4K bytes, a 
further base register is used. 

jRegister 1,2,..- TCA; Offsets from register 
12 are used to address the various fields 
in the TCA. The TCA is discussed further in 
chapter 5. Its format is shown in appendix 
A. 

S§His ter_13_j2_Curr ent _DS A : Register 13 
points to the current DSA and is used to 
address the automatic variables declared in 
the current procedure or block. References 
to offsets from register 13 which do not 
appear as names in the assembler language 
listing are references to the housekeeping 
fields held in every DSA. These are 
discussed in chapter 6; the format of the 
housekeeping information in a DSA is given 
in appendix A. 

Register _4; When the DSA is larger than 
3896 bytes register U is used as a base for 
compiler generated temporaries. 
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Register usage in library modules is 
different from that in compiled code. It is 
shown in figure 2.6. 

In both library and compiled code usage, 
register 12 points at the TCA, and register 
13 at the current DSA. Registers lU and 15 
are used by both library subroutines and 
compiled code to branch and link between 
routines. 

A further point about library register 
usage is worth noting. Registers 14 through 
4 are normally saved by the library. This 
is because the majority of library 
subroutines use only these registers. 
Consequently, time can be saved by reducing 
save-restore requirements. However, some 
library routines also save one or more cf 
registers 5 through 11. 



Handling and Addressing Variables and 
Temporaries 

AUTOMATIC VARIABLES 



Automatic variables have storage allocated 
on a procedure or begin-block basis. 
Variables whose length is known during 
compilation have storage allocated within 
the DSA of the block in which they are 
declared. Variables whose length is not 
known until execution have their storage 
allocated in variable data areas (VDAs) . 
VDAs are held in the last-in/first-out 
storage stack and are acquired in the 
prologue code after the DSA has been 
acquired. The same method is used as is 
used for acquiring the DSA (see above under 
"Prologue Code.") 
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Automatic variables, when used in the 
block in which they are declared, are 
addressed from register 13, if they are 
held in the DSA. If they are held in a 
VDA, a separate base is set up for the VDA 
and they are addressed from this. 



REGISTER USAGE (Library) 



Register 



Usage 



1 
2 
3 

4 

5 

6 

7 

8 

9 

10 

11 

12 



13 
14 



15 



Work register 

Work register 

Program base register 

(dedicated) 

Work register 

Work register 

Work register 

Work register 

Work register 

Work register 

Work register 

Work register 

TCA pointer (dedicated in 

both library and compiled 

code) 

DSA pointer 

Work register (always used 

for branch-and-link to other 

routines) 

Work register (used with 

register 14 for 

branch-and-link) 



Figure 2,6. Library register usage 

Automatic variables known in any 
procedure or block are those that are 
declared in that procedure or block, or in 
any encompassing .procedures or blocks. 
The method used to address automatic 
variables in outer blocks is as follows. 
The address of the DSA of the block in 
which the required variable was declared 
is placed in the current DSA. This 
address can then be accessed from register 
13. This is done in the prologue. 
Frequently, the value is retained in the 
registei: used in the initial load and not 
reloaded when the variable is accessed. 
Typical code would be 

L 7^96(0,13) Pick up address of 
correct DSA 

L 8,108(7) Place value in register 
8 



containing intermediate results. These 
fields are known as tgmporary_variables 
(temporaries) and are allocated within the 
DSA of the associated block, provided that 
the size of storage required is known at 
compile time. Temporaries are addressed 
from register 13, unless the DSA is longer 
than 4096 bytes. Because temporary 
storage is continually being reused, the 
same offset will not always refer to the 
same temporary. 
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Where a temporary is needed to hold a 
value for an adjustable variable, its size 
is not predictable until execution. In 
such cases, a VDA is acquired for the 
temporary value. 



CONTROLLED VARIABLES 



Controlled variables are addressed through 
the pseudo-register vector, as described 
below under the heading "Pseudo-Register 
Vector (PRV)". When no allocations of the 
controlled variable have been made, the 
PRV offset points to the dummy FCB. 
Otherwise, it points to the most recent 
allocation of the controlled variable. 

Each controlled variable is headed by a 
four-word control block that holds the 
address of the previous allocation (if 
any) , the length of the variable 
(including the control block), the 
pseudo-register vector offset, and the 
task invocation count. The format of this 
control block is shown in appendix A. 

Storage for controlled variables is 
allocated in non-LIFO storage. If there 
is room in the ISA, it is allocated within 
the ISA. Otherwise, a GETMAIN macro 
instruction is issued to obtain storage. 

Stacking and unstacking of controlled 
variables is handled by a resident library 
routine, IBMBPAF. IBMBPAF calls on 
IBMBPGR to obtain and release the storage. 



BASED VARIABLES 



COMPILER- GENERATED TEMPORARIES 



Because PL/I statements can contain an 
unlimited number of operands, it is 
frequently necessary to set up fields 



Based variables are addressed by using the 
contents of the pointer on which they are 
based. The pointer is addressed in the 
usual manner, depending on its storage 
class. 
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When a based variable is allocated, a 
call to the storage iranagerrent module 
IBMBPGR is made, IBMBPGR acquires storage 
in the non-LIFO dynamic storage area and 
returns the address of the storage in 
register 1. The address held in register 
1 is then placed in the pointer on which 
the allocated variable is based. 

When the variable is freed, a further 
call to IBMBPGR is made to free the 
storage. 

Pointers; Pointers and offsets are held 
as fullwords. The null pointer value is 
X'FFOOOOOO*. 



addresses are held in the following areas: 

Automatic Immediately following 
the housekeeping 
information of the DSA. 

Static At the head of the 

first section of static 
storage. 

Temporaries At the head of 

temporary storage, 
following bases of 
parameters, register 
save area, and 
addresses of any outer 

DSAS. 



STATIC VARIABLES 



Static internal variables are held in the 
static internal control section and are 
addressed from register 3. 

Static external variables are held in 
separate control sections and are 
addressed from an address constant in the 
static internal control section. 



Constants and variables are held in 
order of size, with the smallest first. 
This minimizes the number of items that 
overflow the 4K boundary. 



THE PSEUDO-REGISTER VECTOR (PRV) 



Addressing_Controlled_Variables_and 
Files 



ADDRESSING BEYOND THE 4K LIMIT 



As described above, variables can, in the 
simplest case, be addressed by using an 
offset from one of the base registers. 
However, as the space required for any 
particular type of storage can exceed the 
maximum offset allowed in addressing (4096 
bytes), it is necessary to have a scheme 
to allow addressing of variables beyond 
this limit. 

The method used is to divide storage 
for automatic variables,, temporaries, and 
static variables into sections of 4096 
bytes. The addresses of the second and 
subsequent sections are then placed in the 
first section. Addressing of an automatic 
variable beyond the 4 096-byte limit is 
typically done by code resembling the 
following: 

L 6,92(0,13) Place address of 4K 

boundary in register 6. 



AH 7,96(0,6) 



Address variable by 
using offset from 4K 
boundary placed in 
register set up in last 
instruction. 



A similar system is used for addressing 
any static variables which are at an 
offset greater than 4 096 bytes. The 



In order to address controlled variables 
and files, a control block known as the 
pseudo-register vector (PRV) is used. This 
control block is mapped by the linkage 
editor as a dummy section with a fullword 
field for each uniquely named controlled 
variable or file. During execution, the 
addresses of the storage allocated to the 
variables or files are placed in the PRV. 

The use of the linkage editor is 
necessary because controlled variables and 
files may be external and, consequently, it 
may be necessary to access them in 
separately compiled procedures. Other 
external items are compiled as CSECTs, but 
this is not possible for files or 
controlled variables because their 
associated storage is not allocated until 
execution, controlled variables have 
storage allocated during the execution of 
an ALLOCATE statement; files are addressed 
from file control blocks (FCBs), which are 
created during execution. 

References to controlled variables and 
files are compiled as Q-type address 
constants. During link-editing, the DXD 
facility of the linkage editor is used, and 
the PRV is set up as an external dummy 
section. Each uniquely named file or 
controlled variable is allocated an offset 
within this dummy section, and the Q-type 
address constants are replaced by this 
offset. 
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During compilation 

1. Each controlled variable or file 
reference is compiled as a Q-type 
address constant that will be used as 
an offset within the PRV. 

2. The compiler generates a DXD 
instruction for every item requiring 
pseudo-register addressing. 

During link-editing 

[l. The nuirber of unique names requiring 
ps€5udo-register addressing is 
calculated and placed in a field that 
can be accessed by a CXD instruction. 

2. Each reference to a name generated as 
a Q~type address constant is replaced 
by the appropriate offset from the 
start of the PRV. 

During program initialization 

1. The length required for the PRV is 
obtained by use of a CXD instruction. 
Storage for the PRV is then obtained 
in the program management area. The 
address of the PRV is placed in the 
TCii. 

2. The address of the dummy FCB is 
placed in every field of the PRV. 

During execution 

1. When storage is allocated to the FCB 
or controlled variable, the address 
of the storage is placed in the 
associated field in the PRV. 
Comparison with the dummy FCB address 
can then be made, to determine 
wh€3ther storage has been allocated 
fo3: the item. 



from the TCA. 

Whenever a new task is attached, the PRV 
of the attaching task is copied into the 
program management area of the attached 
task. This means that, at the point when 
the task is attached, the files and 
controlled variables addressed from the 
subtask will be the same as those in the 
parent task. However, because each task 
has its own PRV, either task may change the 
addresses without affecting the other. 



Initialization of the PRV 



To simplify implicit opening of a record 
I/O file, the PRV is initialized with every 
field set to point to a control block known 
as the dummy FCB. Use of this control 
block as if it were a genuine FCB results 
in control being passed to the open 
routines: the file is opened, and a real 
FCB is created. The address of the real 
FCB is then placed in the PRV, 

Pseudo-register fields for controlled 
variables are also initialized to point to 
the dummy FCB, so that the controlled 
variable allocation mechanism can determine 
whether an allocation has been made by 
comparing the PRV value with the address of 
the dummy FCB. (The address of the duirmy 
FCB is held throughout the program in the 
TCA, so that the comparison can be made.) 



Program Control Data 



Figure 2.7. Use of the pseudo-register 
vector (PRV) 



Program control data comprises pointer, 
offset, file, area, entry, event, task, and 
label data. 



Controlled variables and files are 
addressed via the PRV regardless of whether 
they are external or internal. The 
compiler prefixes internal items with the 
name of their procedure so that their names 
will be unique. The use of the PRV is 
summarisced in figure 2.7. 



Pointer and offset data items are each 
held in a fullword. The data item in both 
cases consists of an address that is held 
right-adjusted in the field, padded on the 
left with zeros. For both data types, the 
null value is represented by hexadecimal 
•FFOOOOOO*. 



The Loccition of the PRV 



The pseudo-register vector is held in the 
program management area, and is addressed 



A file variable is held as a fullword 
containing the address of the declare 
control block (DCLCB) ; the DCLCB 
corresponds to a file constant. 

The formats of area, entry, event, task 
and label data are given in Appendix A. 
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HANDLING DATA AGGREGATES 



ARRAYS OF STRUCTURES AND STRUCTURES OF 
ARRAYS 



PL/I data aggregates are structures and 
arrays, and include both arrays of 
structures and structures of arrays. 



Array elements are addressed from the 
virtual origin of an array. This is the 
point at which the element whose subscripts 
are all zeros is held, or would be held if 
no such element is included in the array. 
Each element can be accessed by using a 
multiplier for each dimension. The 
multiplier is the distance between elements 
in a cross- section of an array. For 
example,, in an array B(9,9) the multiplier 
for the first dimension is the distance 
between elements B(l,l) and B(2,l); the 
multiplier for the second dimension is the 
distance between elements B(l,l) and 
B(l,2). 



If the bounds of the array and the 
length of the elements of the array are 
known during compilation, the values of 
multipliers can be calculated and placed as 
constants in the static internal control 
section. For accessing an element with a 
constant subscript,, the offset from the 
virtual origin can be calculated during 
compilation. If the subscript value is a 
variable, the multiplier must be picked up 
from static storage during execution and 
the value calculated. 



If the bounds or extents of an array are 
not known during compilation, a control 
block known as an a.rray_descriptpr is set 
up. This control block is used to hold 
necessary information about bounds, 
multipliers,, etc. The information is placed 
in the array descriptor during execution. 
Array descriptors are described in chapter 
4. 



Arrays of structures and structures of 
arrays are held as they are declared. 

The array of structures 

1 S(2), 

2 B, 
2 C; 

would be held in the order 



I S(1).B 

L 



S(1).C I S(2).B I S(2).C I 

J 



B and C are known as intgrleaved arrays, 
because the elements within each array are 
not contiguous. 

The structure of arrays 

1 S, 

2 B(2), 
2 C(2); 

would be held in the order 



r 1 

I S.B(l) I S.B(2) I S.C(l) I S.C(2) | 

L J 



Elements are accessed as array elements in 
both cases. In the array of structures 
shown above, both B and C are treated as 
separate arrays with their own virtual 
origins and multipliers. The difference 
would be in the value of the multipliers. 
When possible, the values of multipliers 
are calculated during compilation. When 
adjustable bounds or extents are involved, 
the necessary data for both arrays of 
structures and structures of arrays is 
placed in a structure descriptor (see 
chapter 4) . 



Structures are treated in a similar 
manner. Where all information about a 
structure is known, it is mapped during 
compilation and offsets to each item from 
the start of the structure are known to 
compiled code. If a structure cannot be 
mapped during compilation, it is mapped 
during execution, and the offsets within 
the structure are placed in a control block 
known as a structure _ des criptor . To access 
an item in the structure, compiled code 
finds the offsets and calculates the 
address of each element from them. 
Structure descriptors and the process of 
mapping during execution are described in 
chapter 4. 



ARRAY AND STRUCTURE ASSIGNMENTS 



Assignments between structures and arrays 
of the same format are done by MVC 
instructions. Provided an array is net 
interleaved, an assignment will be made to 
it as a whole, and the elements will not be 
moved one at a time, similarly, structures 
that are contiguous and have the same 
format are moved as a whole. 
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STM 


14,12,12(13) 


BC 


* + 16 


DC 


A (STMT NO TABLE) 


DC 


F'272' 


DC 


A (STATIC CSECT) 


L 


3,16(0,15) 


L 


1,76(0,13) 


L 


0,12(0,15) 


ALR 


0.1 


CL 


0,12(0,12) 


BC 


13,48(0,15) 


L 


15,116(0,12) 


BALR 


14,15 


L 


15,16(0,13) 


ST 


0,76(0,1) 


ST 


13,4(0,1) 


MVC 


72(4,1), 72(13) 


LR 


13,1 


ST 


5,88(0,13) 


MVI 


87(13), X*91' 


MVI 


86(13), X»91" 


MVI 


85(13),,X'C0* 


MVI 


87(13), X'CO' 


MVI 


0(13), X'80" 


MVI 


1(13), X'OO* 


LA 


J4, 176 (0,13) 



Other code as required 



BALR 



2,0 



Store registers of calling program. 

Branch around constants. 

Constant - address of statement number table. 

Constant - length required for new DSA. 

Constant - address of static internal CSECT filled in 

by linkage editor. 

Set up R3 as static base. 

Set Rl to old NAB (start of new DSA). 

Place length required for new DSA in RO. 

Add old NAB (in Rl) and length required for DSA (in 

RO). 

Compare with EOS in TCA. 

Branch around library call if new DSA fits segment. 

Load address of stack overflow routine (IBMBPGRC) from 

TCA. 

Branch to overflow routine. 

Restore R15 to previous value. (May have been changed 

by library call) 

Store new NAB in new DSA. 

Place backchain in new DSA. 

Move address of LWS from old DSA to new DSA. 

Point register 13 at new DSA. 

Set up static backchain. 



Set up enable cells - see chapter 7. 

Set up housekeeping flags - see appendix A. 

Set up base for temporaries. 

Other tasks may be carried out at this point. (Such 
as, initialization of variables with the initial 
attribute, acquiring a VDA for adjustable variables, 
and setting up certain error-handling fields.) 
Set R2 as program base. 



Figure 2. 8. Typical prologue code 



Handling Flow of Control 



ACTIVATING AND TERMINATING BLOCKS 



In PL/I, five types of statement can result 
in non-consecutive flow of control. These 
statements are: 

CALL statements 
END statements 
RETURN statements 
Function references 
GOTO statements 

The first four of these are concerned with 
the block structure of the PL/I program and 
involve passing control from one block to 
another. GOTO statements can result in 
branches to code that is either in the 
current block, or in any other active 
block. 

Consecutive flow of control also ceases 
when an error or program interrupt occurs. 
The methods used to handle error and PL/I 
condition situations are described in 
chapter 7, "Error Handling." 



CALL, END, and RETURN statements, and 
function references all result in the 
activation or termination of blocks. The 
block structure of PL/I, as explained in 
chapter 1, is implemented by means of a 
hierarchy of DSAs. 

Each block (begin block, procedure 
block, or on-unit block) executes on its 
own program base that is set up at the end 
of the prologue code for each block. This 
base is marked in the object code listing 
with: 

* PROCEDURE BASE 

In the PL/I optimizing compiler, blocks 
are always called by means of a BALR 
instruction on registers 14 and 15. Within 
the prologue code, the registers are stored 
in the DSA of the calling block, and a new 
DSA is set up to hold the automatic 
variables of the new block plus a certain 
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R13 



Housekeeping information 
See appendix A 



Items < 9 bytes in length 

Held in alignment order: 
doubleword 
fullword 
halfword 
byte 
bit 



Items 9 - 2048 bytes in length 

Held in alignment order as above 



Items > 2048 bytes 

Held in alignment order as above 



Parameter storage area 

Addresses of any parameters 
passed to the associated 
procedure are stored here 



Register bind storage area 

Used by compiled code when 
registers must be saved 



Local temporary storage 

Used for temporaries required 
for duration of statement 



Global temporary storage 

Used by temporaries required 
for duration of block 



Storage for automatic 
variables declared in 
the block, dynamic 
ONCBsetc. 



Temporary storage 



Figure 2.9. Contents of typical compiled code DSA 
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amount of environmental information such as 
the enablement or disablement of certain 
conditions. 

When a block is terminated, the 
registers of the calling block are 
restored, and a branch is made on register 
14. This immediately returns control to the 
instruction after the BALR issued in the 
preceding block. The DSA of the called 
block is automatically discarded because 
all fields in the DSA, including the 
pointer to the next available byte of free 
storage, were addressed from register 13. 
Because register 13 has been altered, the 
values that apply to the calling block 
automatically become current when the 
calling block's registers are restored. 



PROLOGUE AND EPILOGUE CODE 



Except for certain single statement on- 
units, every PL/I begin block or procedure 
block has a prologue and an epilogue. The 
prologue prepares the environment for the 
associated block and acquires storage for 
automatic variables, compiler-generated 
temporaries, and workspace. The epilogue 
frees the storage acquired for the block, 
restores the registers of the caller, and 
returns control to the caller. 



Prologue 



The prologue appears on the object-program 
listing between REAL ENTRY and PROCEDURE 
BASE or BLOCK BASE. Every prologue has to 
acquire a dynamic save area (DSA) for the 
new block. (The DSA is a register save 
area concatenated with housekeeping 
information,, plus storage for automatic 
variables and temporaries.) Other jobs that 
may be done in the prologue code are: 

• Initialization of automatic variables 
that have the INITIAL attribute. 

• Initialization of pointers and locators 
that have the INITIAL attribute. 

• Movement of parameter addresses passed 
to the procedure to the correct 
location. 

• Acquisition of storage for adjustable 
variables. 

• Initialization of certain items for 
argument lists. 

• setting-up certain interrupt-handling 
information such as ONCBs and enable 



cells. (See chapter 7.) 

An example of prologue code is shown in 
figure 2.8. 

After saving the registers, the prologue 
tests to see if there is enough room for 
the DSA in the current segment of storage. 
This is done by adding the length of the 
new DSA, calculated at compile time, to the 
address of the next available byte. If the 
result is greater than the end-of-segirent 
pointer (EOS) placed in the TCA during 
initialization, the library overflow 
routine (IBMBPGR) is called to try to to 
acquire a further segment from the free- 
area chain. If space for the DSA is 
available, the next-available-byte pointer 
(NAB) is updated to point at the first 8- 
byte boundary beyond the end of the new 
DSA. The remaining instructions set up 
housekeeping fields and point registers at 
various standard fields, including register 
13 to the start of the new DSA, and 
register 4 to the start of storage for 
temporaries. The final BALR instruction 
establishes register 2 as the program base 
register. 

Two backchains are set up. The dynamic 
backchain,, which points to the DSA of the 
calling or preceding block, and the static 
backchain, which points to the DSA of the 
statically encompassing block. For the 
main procedure, the dynamic backchain 
points to the dummy DSA, and the static 
backchain is set to zero. The address of 
the statically encompassing block is passed 
in register 5. 

Static backchains are used in tracing 
the scope of names and the enablement of 
PL/I conditions. 

For PL/I procedures with COBOL or 
FORTRAN in the OPTIONS option, the prologue 
is considerably different. See chapter 13, 
" Interlanguage Communication . " 

The format of the DSA is shown in figure 
2.9; full details are shown in appendix A. 



Epilogue 



Epilogue code consists of the instructions 
generated for END or RETURN statements. 
These instructions restore the registers to 
the values that were held when the current 
block was called. The register values are 
those stored in the previous DSA. Typical 
epilogue code is shown in figure 2.10. 

The completion of a main procedure 
results in the raising of the FINISH 
condition, and this may result in the 
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execution of an on-unit. Consequently, the 
address of the current DSA and the address 
of the current statement must be retained 
(the DSA is needed to search for the on- 
unit; the address of the current statement 
is needed if a SNAP trace is requested in 
the FINISH on-unit) . Epilogue code for a 
main procedure therefore takes a different 
form to that generated for a subroutine. 



Function References 



Function references are compiled in exactly 
the same way as CALL statements. If the 
function returns a value, an extra field is 
placed as the last argument in the list. 
The returned value is placed in this field 
when the function is completed. Typical 
code would be: 



Epilogue code for main procedure 



LR 

L 
L 

LM 



0,13 

13,4(0,13) 

14,12(0,13) 

2,12,28(13) 



BALR 1,14 



Save current DSA 

address 

Chainback 

Pick up value of R14 

Restore registers 2 

through 12 

Branch to 

initialization 

routine retaining 

current address in 

Rl 



Epilogue code for subroutine or begin 
block 



L 13,4(0,13) 
LM 14,12,12(13) 



BR 



14 



Chainback 

Restore registers of 

preceding block 

Return 



OOOIFE 41 90 6 0B4 

000202 

000206 



50 90 3 OBC 
41 90 6 OBO 



LA 9,B 

ST 9,188(0,3) 

LA 9, A 



00020A 
00020E 18 56 



50 90 3 OCO ST 9,192(0,3) 
Set up parameter list 



LR 5,6 
Load static backchain address 



000210 41 10 3 OBC LA 1,188(0,3) 

Point register 1 at parameter 
list 

000214 58 FO 3 008 L 15, A. .. DOUBLE 
Place address of function 
(DOUBLE) in R15 

000218 05 EF BALR 14,15 

Branch to function 



Figure 2.10. Epilogue code 



END Statement 



CALL Statements 



CALL statements are executed by picking up 
the address of the block to be called from 
static storage. A BALR instruction is then 
carried out on registers 14 and 15. If 
arguments are being passed to the called 
procedure, an argument list is set up in 
temporary storage, the first bit of the 
last argument is set to '1', and register 1 
is pointed at the argument list. 



Typical code would be: 

00031A 18 50 LR 5,13 

Load static backchain address 

00031C 58 FO 3 020 L 15, A... X 

Pick up address of procedure X 

000320 05 FF BALR 14,15 

Branch to procedure 



END statements result basically in 
restoring the registers of the calling 
block and branching to the value held in 
register 14 of that block. 

Code compiled for an END statement of an 
internal block takes the following form: 

000402 58 DO D 004 L 13,4(0,13) 
Pick up DSA backchain 

000406 98 EC D OOC LM 14,12,12(13) 
Restore registers 

00040A 07 FE BR 14 

Branch to procedure 

For main procedures, certain further 
actions have to be taken. Because the end 
of a main procedure raises the FINISH 
condition, it is necessary to save the 
current value of register 13 so that the 
error handler may search the DSA chain for 
a FINISH on-unit- As it is possible to 
request a SNAP trace in a FINISH on-unit, 
it is also necessary to save the address of 
the END statement. For this reason, the 
branch is made with a BALR instruction 
rather than a branch instruction as used 
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for internal blocks. Typical code would 
he: 

00188C 18 OD LR 0,13 

Save current DSA address in RQ 

00188E 58 DO D 004 L 13,4(0,13) 
Pick up DSA backchain 

001892 58 EO D OOC L 14,12(0,13) 
Restore register 14 

001896 98 2C D OlC LM 2,12,28(13) 
Restore registers 2 through 12 

00189A 05 IE BALR 1,14 

Branch to initialization 
routine saving branch address 
in register 1 



statement. Consequently, interpretive code 
is used for label variables. 

For GOTO statements to a label constant 
within the block, the compiler produces a 
straightforward branch instruction. For 
GOTO statements that may pass control to 
another block, compiled code calls the 
interpretive code in the TCA. 

Interpretive code to handle a GOTO out 
of block is held in the TCA. To implement 
a GOTO that will or may transfer control 
out of the block, compiled code branches to 
code in the TCA. The code in the TCA 
checks to see whether it is one of a small 
number of special cases, and, if it is, 
calls a library routine — IBMBPGO. In 
other circumstances, the GOTO code in the 
TCA handles the branch and any block 
termination involved. 



RETURN Statement 



RETURN statements are executed in a similar 
way to END statements, but result in the 
termination of a procedure rather than a 
block. Consequently, before the 
restoration of the registers, a chainback 
must be made to the correct DSA. A 
chainback is made through any begin blocks. 
The depth of nesting can be determined 
during compilation, so the backchain can be 
loaded the required number of times before 
the branch is made. 

Typical code would be: 

0003F0 58 DO D 004 L 13,4(0,13) 
Pick up DSA backchain 

0003F4 98 EC D OOC LM 14,12,12(13) 
Restore registers 

0003F8 07 FE BR 14 

Branch to procedure 

Note: If the procedure in which the RETURN 
statement occurs is a main procedure, the 
code will take the form compiled for an END 
statement for an external procedure (see 
above. ) 



GOTO STATEMENTS 



The implications of a GOTO statement depend 
on whether the label branched to is within 
the block or external to it. If the label 
is outside the block, the branch implies 
that one or more blocks must be terminated. 
If the label in the GOTO statement is a 
label variable, it is not always possible 
to determine during compilation whether the 
label will be in the same block as the GOTO 



GOTO within a Block 



The optimizing compiler produces code that 
assumes that the registers retained across 
the execution of a labeled statement will 
be 2, 3, 12, and 13. These are the program 
base, the static base, the temporary base, 
the address of the TCA, and the address of 
the current DSA. All other register values 
may be different when control passes 
through the labeled statement on different 
occasions. 

The enablement of conditions may differ 
in the GOTO statement and in the labeled 
statement. Within a block, the enablement 
status may be varied only for the duration 
of a single statement. The GOTO therefore 
resets the block enablement status before 
the branch is taken. If the labeled 
statement has a different enablement status 
from the block, it will be automatically 
reset in the labeled statement. 

As explained in chapter 7, "Error and 
Condition Handling, " the enablement of 
conditions is recorded by enable cells. 
Two sets are used: the block enable cells 
retain the enablement situation at the 
start of the block, which can consequently 
be restored at any time; the current enable 
cells hold the enablement situation that is 
current, which, as explained earlier, may 
differ from that at the start of the block. 

A GOTO within block normally takes the 
form of a simple branch instruction plus 
any alteration of the enablement bits that 
may be necessary to reset the enablement 
situation to that at the start of the 
block. Typical code would be: 



OOOFIA 47 FO 2 0C8 



B 



INPUT 
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Branch to correct address in 
compiled code (label name is 
"INPUT") 

The optimizing compiler attempts to 
retain the same block base for all branches 
within a block. However, this is not always 
possible and, if the code for the block is 
longer than 4096 bytes, it may be necessary 
to set up a new base when a GOTO statement 
is executed. As all labels are stored with 
both their address and their base this 
presents no problem. The address of the 
label and the value of its base form the 
value of the label constant. The value of 
the base is placed in register 2, and a 
branch is made to the label address. 

When a GOTO to a label within the block 
is made, there is no need to reset 
registers 3, 4, 12, or 13 as these are not 
altered within a block. When 
OPTIMIZE (TIME) is specified an attempt is 
made to retain register values across 
labels. 

Labeled statements within a block have 
an effect on optimization in that, apart 
from the bases and block addresses 
mentioned above, values cannot be retained 
in registers beyond a labeled statement. 



made for a qualified CHECK ONCB, so that 
the enable cells may be set to the start- 
of-block situation in this ONCB. 

In a similar manner, it may be necessary 
to restore the NAB value to that at the 
start of the block. This will be necessary 
if the statement that invoked the block 
acquired a VDA. The start-of-block NAE 
value is retained in the DSA and is known 
as the end-of-prologue NAB. If a VDA has 
been acquired, the fact is flagged in the 
flag byte of the DSA, and the GOTO places 
the end-of-prologue NAB value in the 
current NAB field. 

Such action is never required within a 
block, as VDAs are only acquired for the 
duration of one statement and are never 
used for GOTO statements. Typical code 
would be: 

GOTO label-constant (out of block) 

000226 18 E6 LR 15,6 

Place address of DSA in Rl5 

000228 Ul EO 3 088 LA 14,136(0,3) 
Place address of label 
constant in R14 

00022C 47 FO C 080 B 128(0,12) 
Branch to GOTO code in TCA 



GOTO out of Block 



GOTO statements that transfer control from 
a block have to overcome the problems 
described above, plus problems of block 
termination. 

For a GOTO out of block or to a label 
variable, compiled code makes a call to the 
GOTO code in the TCA, which is held at 
offset 128 (decimal) . The GOTO code 
receives, through registers 14 and 15, 
either the contents of the label variable 
or the equivalent information for a label 
constant, namely the address at which the 
label constant is held, and the address of 
the DSA of the block in which the label 
appears. 

The GOTO code restores registers 3 and 4 
from the DSA passed to it, loads register 2 
from the second word of the label constant, 
and loads register 13 from register 15. It 
then branches to the appropriate point in 
code which is picked up from the address of 
the label constant, passed in register 14. 

The enablement situation at the start of 
the block has to be be restored, and this 
is done by setting the current enable cells 
in the DSA to the value of the block enable 
cells. If the current enable cells 
indicate that CHECK is enabled, a search is 



GOTO Label Variable 



GOTO label variable statements are treated 
in different ways depending on whether 
optimization has been specified. 

For NOOPTIMIZE, they are all treated as 
GOTO out of block; for OPTIMIZE (TIME), a 
check is made to determine whether they 
could be out-of- block branches. The check 
is made by testing a label list, which is a 
list of the label constants to which the 
label variable may be assigned. If the 
programmer has supplied a label list, it is 
used. Otherwise, a list is generated 
containing all the label constants that are 
assigned to label variables. If a branch 
to any of the labels in the list could 
result in a GOTO out-of -block, all GOTO 
statements referring to the label variable 
are treated as GOTO out-of- block 
situations. Typical code would be: 

GOTO label-variable 

OOOODO 98 EF D 0A8 LM 14,15,168(13) 
Load R14 and Rl5 with label 
variable 

0000D4 47 FO 080 B 128(0,12) 
Branch to GOTO code in TCA 
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Errors when Using Label Variables 



iRlthough it is invalid PL/I, it is possible 
for a GCrc statement using a label variable 
to result in transfer of control to an 
inactive block. The optimizing compiler has 
no method of checking such errors, whose 
consequences are unpredictable. Such errors 
can occur because a label variable is not 
reset when the block containing the label 
constant to which it refers is terminated. 
When an attempt is made to GOTO a label 
variable, the address of the DSA is passed 
in register 14. The GOTO code assumes this 
address to be the address of an active DSA, 
and acts accordingly. Three possibilities 
arise: 

1. The original DSA will not have been 
overwritten, and the program will 
execute. 

2. The original DSA will have been 
overwritten with the DSA of another 
block. The results are then 
unpredictable, as the code branched to 
will be accessing an incorrectly 
mapped DSA. 

3. The original DSA will have been 
overwritten with other information. 
Again, the results are unpredictable, 
but may result in an interrupt in the 
error handler because the backchaining 
will not be correctly set up. 

It should be noted that, because of the 
method used to allocate DSAs, the chances 
of one DSA starting at the same address as 
a previous DSA are high* 



initialization is done during the execution 
of the prologue of the block that contains 
the on-unit. 

The error handler loads the information 
in the label variable or the label 
temporary into registers 14 and 15, and 
calls the GOTO code in the TCA. 



Interpretiye_GOTO^routines 



If the test in the GOTO code in the TCA 
reveals that an abnormal situation exists, 
the interpretive GOTO routine is called. 
This routine is a subroutine of the program 
initialization routine. 

Two abnormal cases can arise: 

GOTO out of SORT exit routine 

GOTO from an event I/O on-unit 
(certain cases only) 

When either of these situations could occur 
a flag is set in the TCA. Sort exits are 
also flagged in the DSA of the procedure 
involved. 

The SORT exit DSA requires special 
action because the GOTO will involve the 
termination of SORT if it transfers control 
to another block. 

The GOTO during an event I/O on unit can 
cause the termination of a number of WAIT 
statements. This involves removing 
information about these statements from the 
various chains that are set up during event 
I/O. 



GOTO-only On-Units 



As explained in chapter 7, certain on-units 
are not executed as separate program 
blocks. Instead, the required action is 
taken under the control of the error 
handler. On-units containing only a GOTO 
statement (GOTO-only on-units) are handled 
in this way. 

The error handler accesses on-units 
through control blocks known as ON control 
blocks (ONCBs). The ONCB for a GOTO-only 
on-unit is specially flagged, and the last 
word of the ONCB is initialized to hold an 
offset. At this offset in the DSA of the 
block containing the on-unit, the address 
of the label information is held. For a 
label variable, the offset contains the 
address of the label variable; for a label 
constant, the offset contains the address 
of a label temporary that is initialized to 
the value of the label constant. The 



These two situations are explained 
further under the headings "SORT/MERGE' 
"WAIT" in chapter 11. 



and 



If CHECK enablement has to be changed 
during an abnormal GOTO, the library 
routine IBMBPGO is called by the 
interpretive GOTO routine. To handle the 
situation. IBMBPGO is described in the 
licensed publication OS/360 PL/I Resident 
Library Program Logic. 



Argument and Parameter Lists 



In PL/I usage, a parameter list is a list 
of the items a program expects to be 
passed; an argument list is a list of the 
items that are passed by the calling 
routine. 

Between PL/I routines, addresses are 
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always passed rather than the arguments 
themselves. For strings, structures, 
arrays, and areas, the addresses of 
locators are passed rather than the 
addresses of the arguments themselves. The 
format of locators and the reasons for 
their use are given in chapter 4. 

I When arguments are passed to routines 
I whose entry points are declared with the 
I ASSEMBLER, COBOL, or FORTRAN attributes, 
I the address of the data itself must be 
I passed. The method used is described in 
I chapter 13 "Inter language Communication". 

Arguments are passed in an argument list 
addressed by register 1. Normally the list 
is set up in static storage. The addresses 
are loaded into consecutive registers and 
placed in the list by an STM instruction. 
If the procedure is reentrant or recursive, 
the list is moved into the temporary 
storage area in the DSA before the call is 
made. 

The addresses passed in the argument 
list are moved into the parameter storage 
area, which is held at the head of 
temporary storage and is addressed by 
register 4. (See figure 2.8.) Parameters 
are then accessed by picking up the 
addresses from this area. 

Dummy arguments, when they are required, 
are set up by the calling program. 
Consequently, the called program can treat 
all arguments in the same manner. 



and 15. 

r 



LA 1,40(0,4) Point Rl at argument 

list 
LA 14,V0..U(11) Store address of 

argument in register 
LA 15,DED..V0.. Store address of 

UCll) argument in register 

STM 14,15,0(1) Load into argument 

list 
L 15,A, .IBMBSLOA Pick up address of 

routine from static 

internal control 

section and place in 

R15 
BALR 14,15 Branch and link to 

routine 

Example 1. Call to library routine that 
has been link-edited and whose address 
is held in the static internal control 
section. The arguments passed are 
addressed by register 1. 

L 15,116(0,12) Load address of 

routine held in TCA 

BALR 14,15 Branch and link to 

routine 

Example 2. Call to library routine 
whose address is held in the TCA 



Figure 2.11. Examples of library 
calling sequences 



LIBRARY CALLS 



Library calls are a feature of every object 
program. All library calls that appear in 
the object-program listing are to modules 
in the resident library. Transient library 
routines are called by bootstrap routines 
which are held in the resident library. 

The number of library calls used depends 
on the source program and the level of 
optimization specified. For OPTIMIZE 
(TIME), the minimum number of library calls 
will be made. If NOOPTIMIZE is specified, 
library calls will be made where this will 
speed compilation. The standard default is 
NOOPTIMIZE. 

Figure 2.11 shows examples of sequences 
used for calling library modules. The 
majority of library calls can easily be 
recognized by the appearance in the listing 
of the letters "IBMB" followed by four 
letters specifying the module name and 
entry point. To call a module, its address 
is loaded into register 15, and a BALR 
instruction is carried out on registers 14 



The fifth letter of the entry point name 
is mnemonic, indicating the type of module 
that is being called. Figure 2.12 gives 
the meaning of the mnemonics. Full details 
of the library modules are given in the 
program product publications OS PL/ I 

Transient_Library: Program_Logic and OS 

PL/I_Resident_Libraryj.___Pro2ram_Loc[ic. 

A further discussion of library module 
naming conventions is given chapter 3. 



§§£ting-yp_Ar2urr!ent_Lists 



Before a call is made to a library module, 
an argument list must normally be set up. 
This is done in one of several ways, 
depending on the library module. The 
majority of library calls require the 
method shown in figure 2.11, example 1. 
This consists of loading the list into 
sequential registers starting at register 
14, and then using a store-multiple 
instruction to place the arguments into an 
area of static storage, whose address is 
then loaded into register 1. Argument 
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lists are set up as far as possible during Addressin3_the_Subroutine 



r 

1 IBMBA 


Array handling | 


1 IBMBB 


String handling | 


1 IBMBC- — 


Conversion | 


1 IBMBE 


Error handling | 


1 IBMBI 


Interlanguage coinitiunication | 


1 IBMBJ 


Date/time/delay/wait | 


1 IBMBK 


Dump/sort/checkpoint/restart | 


1 IBMBM 


Mathematical | 


1 IBMBO- — 




1 IBMBR- — 


Record I/O | 


1 IBMBS 


Stream I/O | 


1 IBMBT 


Completion pseudovariable | 


L 


routine | 

J 



As can be seen in example 1 of figure 2.11, 
library addresses are generally held in 
static storage and addressed as an offset 
from register 3. However, the addresses of 
certain library routines are held in the 
TCA or the TCA appendage and addressed from 
register 12. They are addressed either 
directly or indirectly as shown in example 
2 of figure 2.11. The names of these 
routines do not appear on the listing; 
however, they can be identified by their 
offset from the start of the TCA (see 
figure 2.13). 



Figure 2.12. Mnemonic letters in 

library module entry-point 
names 



Offset from 


Name of 


Use 


start of TCA 


module 




(Register 12) 


entry 
point 










Decimal 


Hex 






72 


48 


IBMBPGRD 


Stack overflow 
routine to 
get VDA 


84 


54 


IBMBEFL 


FLOW module 


108 


6C 


IBMBPGRA 


Get non-LIFO 

dynamic 

storage 


112 


70 


IBMBPGRB 


Free non-LIFO 

dynamic 

storage 


116 


74 


IBMBPGRC 


Stack overflow 
routine for 
prologue 


120 


78 


IBMBERRB 


Error handler 

software 

interrupt 


26U 


108 


IBMBJWTA 


WAIT module 


268 


IOC 


IBMBTOCA 


Completion 

pseudovariable 

routine 


272 


110 


IBMBTOCB 


Event variable 

assignment 

routine 



L J 



Figure 2.13. offsets where addresses of 
library modules are held 
in the TCA 



DO-LOOPS 



Where possible, do- loops are carried out by 
means of a BXLE instruction, because this 
is more efficient than using a simple BCT 
instruction. BXLE do-loops can be used 
where the control variable cannot be 
altered except at the head of the loop, and 
where it is not subsequently accessed after 
the completion of the loop. BXLE do-loops 
cannot be used for the outer of a number of 
nested do-loops. For outer loops, other 
branch instructions are used. Code for a 
number of typical do-loops is shown below. 
Note that the code will differ according to 
the content of the loop. 



Source_2rogram 

DO I = 1 to 10; 
DO J = 1 to 10; 



END; 
END; 

Object program 
1 • Code_f or_o uter_do- loop 
LH 



5,596(0,3) Pick up 1 from 
constants pool 



STH 
CL.l EQU 



5,1 



Place 1 in I 



compilation and, where necessary, completed 
during execution. 



32 



LH 


5.1 




lELCGCE 


AH 


5,596(0,3) 


Increment and 


lELCGON 


STH 


5,1 


store in I 


lELCGRV 


C 


5,598(0,3) 


Compare I and 


lELCGBB 






constant 10 in 


lELCGBO 






static storage 





BNH 



CL.l 



2 • Cpde„,for inner do- loop 
LH 



LH 
LH 
CL. 2 EQU 



BXLE 



5,596(0,3) Place 1 in 

first operand 

10,596(0,3) Place 1 in 

second operand 

11,598(0,3) Place 10 in 
comparand 



5,10,CL.2 



Increment, 
test, and 
branch if 
necessary. 



Compiler-Generated Subroutines 



The compiler uses internal subroutines to 
carry out certain functions. These have 
the advantage over library modules, because 
they can be tailored for the most common 
case. When special cases arise, the 
library routines are called. Compiler- 
generated subroutines have the further 
advantage that they are internal to 
compiled code and consequently need not 
follow the standard operating system 
calling sequence. 

compiler-generated subroutines are used 
for the following purposes. 



lELCGIA 



lELCGIB 



lELCGOA 



lELCGOB 



lELCGOC 

lELCGMV 
lELCGCL 



Stream I/O input - provides 

address of source of next 

edit-directed data or format 

item 

Stream I/O input - 

housekeeping after 

transmission of data item 

Stream I/O output - provides 

address of target of next 

edit-directed data or format 

item 

Stream I/O output - updates 

FCB, counts data item, and 

frees VDA if one was used 

Stream I/O - processes X 

format items 

Move long (registers 6,7,8,9) 

Compare long (registers 

1,6,7,8,9) 



Compare long bits 
Dynamic ONCB chaining 
Revert VDA chaining 
Test for '!• bits 
Test for *0" bits 



Compiler-generated subroutines are held in 
separate control sections and are printed 
at the head of the object-program listing 
when they are used in a program. 



Optimization and its Effects 



Optimization is the attempt to produce the 
most efficient possible object program. 
The OS PL/I Optimizing Compiler adopts a 
threefold approach: 

1. It attempts to compile each statement 
in the most efficient manner. 

2. It modifies the resulting code for 
each block, in an attempt to make it 
more efficient (for example, by 
maintaining values in registers and by 
using common control blocks for 
similar items) . 

3. It examines the source program to 
discover whether statement flow can be 
reorganized to produce a more 
efficient program (for example, by 
moving code out of loops ) . 

The effect of specifying the compiler 
option OPTIMIZE (TIME) is that the compiler 
loads and calls the optimization phases, 
and executes optimization code in other 
phases. The optimization phases are 
described in the publication OS PL/ I 
Optimizing_Cgmpiler; P rogram L o gic . 

When NOOPTIMIZE is specified, the 
optimization phases are not called; no 
attempt is made to study the flow of the 
program, and the examination of compiled 
code for possible improvements is not 
undertaken on a global basis. More library 
calls will generally be made if NOOPTIMIZE 
is specified. 



EXAMPLES OF OPTIMIZED CODE 



A number of the more noticeable effects of 
optimization are shown below. These show 
code sequences which may prove difficult to 
understand without knowledge of the 
objectives of optimization. Where possible, 
the examples of code given are expansions 
of the examples shown in the language 
reference manual for this compiler. The 
examples do net cover all optimization 
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carried out by the compiler. 



Ob j ect progr am 



In 



Elitnination_of_Comirign_Ex2ressions 



Elimination of common expressions is 
handled, by avoiding multiple calculations 
of the same expression, the value being 
retained either in temporary storage or in 
a register. In the examples shovm below, 
the common expression is "B+C". In the 
first example, the value is held in a 
register. In the second, it is held in 
temporary storage, because the value to 
which it is first assigned is altered, 
certain circumstances, the code could be 
compiled to move the value from the 
variable to which it was originally 
assigned to the second variable. 

Exam2l€!_l£_Value_held_in_register 



Source program 

2 A=B+C; 

3 IF X<y THEN X=Y; 
U D=B+C; 



Qb2ect_ 2£ogram 

♦ STATEMENT NUMBER 2 
000062 78 00 D OM 
00006>6 7A 00 D 0A8 
00006A 7 00 D OAO 

* STATEMENT NUMBER 3 



00006E 
000072 
000076 
00007A 
00007E 
000082 



78 60 D OAC 

79 60 D OBO 
47 BO 2 020 
78 60 D OBO 
70 60 D OAC 



LE 


0,B 


AE 


0,C 


STE 


0,A 


LE 


6,X 


CE 


6,Y 


BNL 


CL.2 


LE 


6,Y 


STE 


6,X 



CL.2 EQU ♦ 



♦ STATEMENT NUMBER 



* CALCULATION OF COMMONED EXPRESSION 

FOLLOWS 

000082 70 00 D OB*! STE 0,D 



Exam2le_2£^ Value held in temporary^storage 



2 
3 
4 



A=B+C; 

IF X<Y THEN A=6; 

D=B+C; 



Note: A may be altered before subsequent 
use of expression. 



♦ STATEMENT NUMBER 2 
000062 78 00 D 0A4 
000066 7A 00 D 0A8 
00006A 70 00 4 028 
00006E 70 00 D OAO 

♦ STATEMENT NUMBER 3 
000072 78 60 D OAC 



000076 
00007A 
00007E 
000082 
000086 



79 60 D OBO 
47 BO 2 024 
78 00 3 010 
70 00 D OAO 



CL.2 



LE 


0,E 


AE 


0,C 


STE 


0,40(0,4) 


STE 


0,A 


LE 


6,X 


CE 


6,Y 


BNL 


CL.2 


LE 


7,16(0,3) 


STE 


7, A 


EQU 


* 



♦ STATEMENT NUMBER 



* CALCULATION OF COMMONED EXPRESSION 

FOLLOWS 

000086 78 20 4 028 LE 2,40(0,4) 

00008A 70 20 D 0B4 STE 2,D 



Movement of Expressions _out of _LQQEs 



When expressions cannot be altered inside a 
section of code that may be executed a 
number of times, the expression is moved 
out of the loop to a position where it will 
be executed only once, regardless of the 
number of times that the loop is executed. 
The process is known as movement of 
invariant expressions. The most obvious 
example is in do-loops. However, the 
compiler analyzes the source program for 
other types of loop and also moves code 
from these. 

Example 1 shows code moved from a do- 
loop. Example 2 shows code moved from a 
loop that has been detected by the 
compiler. It should be noted that code 
moved out of loops frequently involves 
conversion and is not obvious in the source 
program. 



Example 1; Do^loog 

Sou£ce_program 



DO 1=1 TO N; 
J=3; 

END; 



0b2ect_2rogram 



* STATEMENT NUMBER 2 






000066 


48 EO D 0A2 


LH 


14, N 


00006A 


18 BE 


LR 


11,14 


00006C 


48 AO 3 014 


LH 


10,20(0,3) 


000070 


48 50 3 014 


LH 


5,20(0,3) 


000074 


19 5B 


CR 


5,11 


000076 


47 20 2 024 


BH 


CL.3 
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Source_program 





1- 


— — 










2 




DCL 


C(10) 


FLOAT 


DECIMAL 


(6); 


3 




DCL 


B(10) 


FLOAT 


DECIMAL 


(6); 


4 




DO 


1=1 TO 10 






5 




C(I)=B(I); 






6 




END; 








Ob-ject program 










♦ STATEMENl 


' NUMBER 4 








000066 


48 


60 3 


010 


LH 


6,16(0 


,3) 


00006A 


40 


60 


OAO 


STH 6,1 





Pick up 1 from static 
Place in I 



* INITIALIZATION CODE FOR OPTIMIZED LOOP FOLLOWS 

* CODE MOVED FROM STATEMENT NUMBER 5 



00006E 


48 


EO 


3 


012 


LH 


14,18(0,3) 


000072 


48 


90 


3 


014 


LH 


9,20(0,3) 


000076 


18 


B9 






LR 


11,9 


000078 


48 


AO 


3 


012 


LH 


10,18(0,3) 


00007C 


18 


5E 






LR 


5,14 



Load "4" into R14 from static 
Load "40" into R9 from static 
Load "40" into Rll for BXLE 
Load "4" into RlO 
Load "4" into R5 



♦ CONTINUATION OF STATEMENT NUMBER 
00007E CL.2 EQU ♦ 



♦ STATEMENT NUMBER 5 
00007E 78 45 D 0A4 
000082 70 45 D OCC 

* STATEMENT NUMBER 6 
000086 87 5A 2 018 



LE 4,VO.,B(5) 
STE 4,VO..C(5) 



BXLE 5, 10, CL.2 



Pick up VO. .B+R5 
Place in VC..C+R5 



Increment R5 by 4, test for end of 
loop, and branch or continue 



Figure 2.14. Modification of do-loop control variable 



♦ INITIALIZATION CODE FOR OPTIMIZED LOOP 
FOLLOWS 



♦ CODE MOVED FROM STATEMENT NUMBER 3 
00007A 48 70 3 016 LH 7,22(0,3) 
00007E 40 70 D 0A4 STH 7, J 



* CONTINUATION OF STATEMENT NUMBER 
000082 CL.2 EQU * 



2^i§2t_££23£§S! 



♦ STATEMENT NUMBER 4 
000082 87 5A 2 OIC 
000086 40 50 D OAO 
00008A CL.3 



BXLE 5,10,CL. 
STH 5,1 
EQU * 



* INITIALIZATION CODE FOR OPTIMIZED LOOP 
FOLLOWS 

* CODE MOVED FROM STATEMENT NUMBER 3 
000066 48 EO D OAE LH 14,1 
00006A 4B EO D OBO SH 14, N 
00006E 50 EO 4 028 ST 14,40(0,4) 

* STATEMENT NUMBER 2 



* STATEMENT LABEL L 
000072 78 00 D OAO 
000076 79 00 D 0A4 
00007A 47 20 2 042 

* STATEMENT NUMBER 3 



LE 
CE 
BH 



0,X 
0,Y 
BED 



Example_^2_; Compiler-detected loop 

Source program 

2 LV if X>Y then GOTO BED; 

/♦LOOP begins*/ 

3 a=I-N; 

4 X=xV J ; 

5 GO TO Li /+LOOP ENDS*/ 

6 BED: A=X; 



* CALCULATION OF COMMONED EXPRESSION 
FOLLOWS 

00007E 58 60 4 028 L 6,40(0,4) 
000082 40 60 D OAC STH 6, J 

* STATEMENT NUMBER 4 



♦ END OF COMMON CODE 
000086 50 60 4 030 
00008A 48 60 3 020 



ST 6,48(0,4) 
LH 6,32(0,3) 
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i Source, program 



2 


IF 


[A=D) 1 


(C= 


=D) THEN 






X=Y+ Z ; 








hject program 












♦ STATEMENT NUMBER 2 








000062 


78 00 


D 


OAO 




LE 


0,A 


000066 


79 00 


D 


0A4 




CE 


0,D 


00006A 


47 80 


2 


018 




BE 


CL.3 


00006E 


78 40 


D 


0A8 




LE 


^.c 


000072 


79 HO 


D 


0A4 




CE 


^,D 


000076 


47 70 


2 


024 




BNE 


CL.2 


00007A 






CL 


.3 


EQU 


* 


00007A 


78 60 


D 


OBO 




LE 


6,Y 


00007E 


7A 60 


D 


0B4 




AE 


6,Z 


000082 


70 60 


D 


OAC 




STE 


6,X 


000086 






CL 


.2 


EQU 


* 



Pick up A 
compare A and D 
Branch if equal 
Pick up C 
Compare C and D 
Branch if not equal 



X=Y+Z 



Figure 2.15. Branching around redundant expressions 



Source_£rograra 



X=123; /+COMMONED ITEM*/ 

Y=123*Z; 
V=V**123; 
A=123; /* COMMON ED ITEM*/ 



Obiect_ program 



* STATEMENT NUMBER 2 
000066 78 00 3 020 
00006A 70 00 D OAO 

* STATEMENT NUMBER 3 
00006E 78 20 D 0A8 
000072 6C 20 3 018 
00007A 70 20 D 0A4 

* STATEMENT NUMBER 4 



00007E 


41 


10 


D 


OAC 


000082 


41 


50 


3 


024 


000086 


41 


60 


D 


OAC 


00008A 


58 


FO 


3 


OOC 


00008E 


05 


EF 







* STATEMENT NUMBER 
0000B8 78 20 3 020 
OOOOBC 70 20 D OBO 



LE 
STE 



0,32(0,3) 
0,X 



/*COMMONED ITEM*/ 



LE 2,Z 

MD 2,24(0,3) 

STE 2,Y 



LA 
LA 
LA 



1,V 

5,36(0,3) 

6,V 



LA 5,36(0,3) 

LA 6,V 

L 15,A..IBMBMXSA 

BALR 14,15 



LE 
STE 



2,32(0,3) 
2, A 



/♦COMMONED ITEM*/ 



Figure 2.16. Use of common constants 



00008E 


40 


60 


4 


030 


STH 


6,48(0,4) 


000092 


97 


80 


4 


032 


XI 


50(4), X«80' 


000096 


78 


60 


4 


030 


LE 


6,48(0,4) 


00009A 


7B 


60 


3 


020 


SE 


6,32(0,3) 


00009E 


3A 


60 






AER 


6,0 


OOOOAO 


70 


60 


D 


OAO 


STE 


6,X 



* STATEMENT LABEL BED 
0000A8 70 00 D 0A8 



STE 0,A 



Elimination of Unreachable statements 



* STATEMENT NUMBER 5 
0000A4 47 FO 2 OOC 

* STATEMENT NUMBER 6 



If the source program contains statements 
that can never be executed because they are 
unconditionally branched around, these 
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statements will be ignored by the compiler. 

In th0 example below, the statements 
between ^ and 8 can never be reached. 
Consequently, no code is compiled for these 
statements, and a compiler diagnostic 
message is issued to indicate that this is 
the case* 



Example 
Source. program 



Modificatign_of _,DO-loot 
Variables 



Control 



5 GOTO LABEL; 

6 IF A<B THEN 



IF B<C THEN 



7 ELSE C=B*C; 

8 LABEL: X=X+1; 



Object_ptograin 



♦ STATEMENT NUMBER 5 
00008A 47 FO 2 028 B 

♦ STATEMENT NUMBER 8 

♦ STATEMENT LABEL LABEL 
00008E 78 60 D OAC LE 
000092 7A 60 3 018 AE 



IF A<X THEN 
B=B*C; 



LABEL 



000096 70 60 D OAC 
Compiler message reads: 



6,x 
6,24 
(0,3) 
STE 6,X 



"6,6,6,7 STATEMENT MAY NEVER BE 
EXECUTED. STATEMENTS IGNORED." 



Simplification of Expressions 



When the do- loop control variable is used 
for accessing array elements, it is 
frequently modified to simplify addressing 
of the array elements. 

If, as in the example in figure 2.14, 
the elements of the array are four bytes 
long, it simplifies addressing to increment 
the loop control variable by 4 rather than 
by 1. When this is done, the increment 
becomes the distance between the start of 
successive array elements. Provided that 
the original value of the loop control 
variable is the same as that of the first 
bound of the array, the loop control 
variable in turn becomes the offset of the 
element from the virtual origin of the 
array. 

If the loop control variable is altered, 
this means that the increment and final 
value must also be altered. Thus the loop 
in the example instead of being incremented 
from 1 to 10 by 1, is incremented from 4 to 
40 by 4. Note that the value of the loop 
control variable is set at the start of the 
loop but is not incremented. If the value 
of the loop variable is required after the 
loop has been executed, this type of 
optimization cannot take place. 

In the example, the control variable is 
held in register 5 using a BXLE 
instruction. The array elements are 
addressed by using register 5 as the offset 
from the virtual origins of arrays C and B. 
As register 5 starts the loop with the 
value of 4 and is incremented by 4 for each 
iteration of the loop, this gives the 
correct address. Both arrays begin 4 bytes 
from their virtual origins, and each array 
element is 4 bytes long. 



certain (expressions are simplified for 
speedier; execution. For example, 
multiplication is simplified to addition, 
as in thfe following example. 



Branching around Redundant Expressions 



Example; Multiplication, into_addition 

2 X=3*B 

Object program 

* STATEMENT NUMBER 2 

000065te 78 20 D OAC LE 2,B 

00006 2 3A 22 AER 2,2 

000064 7A 20 D OAC AE 2,B 

000068 70 20 D 0A8 STE 2,X 



If a series of tests are to be made and 
action taken if any of the tests proves 
positive, the compiler takes the requisite 
action as soon as the first positive test 
is found. 

In the example in figure 2.15, a test is 
first made to see if A=D. If so, the value 
of Y-»-z is assigned to X without a further 
test being made to see if C=D. Note that 
the last test is for inequality, so that if 
the variables are equal, control will 
continue with the code that assigns the 
value to X. 
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Rationalization of Program Branches 



When the length of a program is greater 
than 4096 bytes and, consequently, it 
cannot be addressed from one base register, 
an attempt is made to update the base at 
the most efficient point, so that there 
will be as few changes of program base as 
possible during execut>ion. The aim is to 
avoid any program branches which move from 
the scope of one base register to the scope 
of another. 

The program base register is register 2, 
and this is updated when necessary. As 
register 2 is required for in-line record 
I/O and TRT instructions, the program base 
is saved and restored after such use. 



than once are generated only once in static 
storage. Thus for the statements X=768, 
Y=768, the constant value 768 will be 
picked up from the same address in both 
cases. Similarly, compiler-generated 
control information, such as DEDs and 
descriptors (see chapter 4), are generated 
only once if a number of variables require 
identical control information. 

The process of avoiding duplication is 
known as cgmmgning. It should be noted 
that constants may not be commoned if they 
are not used in the same way. In the 
example in figure 2.16, constant '123* is 
stored in a different form for assignment, 
multiplication, and exponentiation. 



Use , of gprnmon^Constants^andcontrol 
Blocks 



constants and control information used more 
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CONTROL NAME 



IBM 


\-\ 


xyz 



Identify module as part of a 
PL/I library 



B=Base Module 
T=Multitasking Module 



Mnemonic of module's 
function 



EXAMPLES 



IBMTPIR 

IBMBEOC 

IBMBJWT 



LINK-EDIT NAME 



IBMBxyz 



IBMBPIR 

IBMBEOC 

IBMBJWT 



ENTRY POINT NAMES 



Resident library modules 



Link-edit name followed by 
A, B, C, etc. 



Transient library modules 



Control name followed by 
A, B, C, etc. 



IBMBPIRA 
IBMBREFA 



Conversion modules sometimes have only two mnemonic letters to identify the function: 
and use two mnemonic letters to identify entry points: 



IBMBCH 
IBMBCHXD 



Figure 3,1, Library module naming conventions 
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Chapter 3: The PL/I Libraries 



This chapter explains the use of libraries 
by the (bs PL/I Optimizing Compiler. The 
topics (bovered are: when and why library 
routines are called, why there is both a 
transient library and a resident library, 
naming inventions, and two implementation 
topics that cover all library modules: the 
use of library workspace and the use of 
weak external references. Also covered are 
the multitasking and shared libraries. 

The OS PL/I Optimizing Compiler is 
designed to be used in conjunction with the 
OS PL/I I Resident Library and the OS PL/I 
Transient Library. These libraries consist 
of sets ; of standard subroutines that are 
used for the majority of interfaces with 
the system and for those jobs that can be 
most efficiently done by the use of 
interpretive subroutines. The main areas 
where library modules are used are: 
input/output, error handling, storage 
management, conversions, mathematical 
functions, and various string- and array- 
handling operations. 

Use Of library routines simplifies 
compilation by enabling the compiler to set 
up an argument list and generate a call to 
a subroiitine, rather than compile the 
complete code. However, library 
subroutines are less efficient than 
compiled code, since they must be 
generalized routines, whereas compiled code 
can be specially tailored to the particular 
program^ being executed. Furthermore, a 
library; call involves the overhead of 
saving and restoring registers, and may 
require! the setting-up of various 
additional control blocks to describe the 
data (siee chapter U) . For these reasons, 
programs that are optimized for time use as 
few libltrary calls as possible. 

The fnajority of interfaces between 
compiled code and the operating system are 
implemented via library routines. This is 
done mainly for reasons of implementation 
convenibnce, as such interfaces are in this 
way localized and minimized. 



Resident and Transient Libraries 



The OS iPL/I subroutine library is divided 
into two separate program products: the OS 
PL/I Resident Library (Program Number 5734- 
LM4) and the OS PL/I Transient Library 
(Program Number 5734-LM5) . Resident 
library modules are link-edited with the 



executable program phase. Transient 
library modules are loaded into dynamic 
storage when they are required; when they 
are no longer needed, the storage is freed 
and may be overwritten. Resident library 
routines have the advantage of speed; 
transient library routines have the 
advantage of saving space. By using both 
types of library, it is possible to produce 
more efficient programs. 

Routines in the transient library are: 
input/output transmitters, open and close 
modules, error message modules, the storage 
management routines and PLIDUMP routines. 
All other library routines are held in the 
resident library, including a number of 
bootstrap routines that load and call 
transient routines. 

The OS PL/I libraries reside on three 
direct-access data sets. The resident 
library is on SYSl.PLIBASE and 
SYSl.PLITASK. The transient library 
resides on SYSl.LINKLIB. 

The internal logic of individual library 
modules is described in the publications OS 

iEE:/I_E§si^§D;t_Libraryx Program Logic and 

OS PL/I Transient Library: Proqram~Logic . 
However, in such cases as I/O, error 
handling, and conversion, where compiled 
code and a hierarchy of library modules are 
used in implementing certain features of 
PL/I, the overall logic is described in 
this publication, similarly, an overall 
explanation of storage management and 
interlanguage communication is given in 
this publication. 



Naming Conventions 



Most PL/I library modules have names of 
seven letters, the first three letters 
being IBM. This identifies the module as 
belonging to one of the PL/I libraries. 
The remaining letters indicate which 
particular library the module was written 
for, and the use of the module. 

Each resident library module has two 
names, the control name (which uniquely 
identifies the module) and the link-edit 
name (which appears in the linkage editor 
map and the object- program listing) . The 
majority of the modules in the OS resident 
library have a control name with the fourth 
letter B, for example IBMBOCL. This module 
has a link- edit name of IBMBOCLA. Some 
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m 



modules, however, have a fourth letter T in 
their control, name, indicating that they 
are used only in a multitasking 
environment. The link-edit names of these 
modules nevertheless have a fourth letter 
B. An example of this is the multitasking 
priority- alteration routine IBMTTPRA. The 
link- edit name for this module is IBMBTPRA. 
(See figure 3.1. ) 

The result of this arrangement is that a 
number of library modules can share the 
same linJc-edit name. Consequently, the 
compiler can generate the same code 
regardless of whether the program is going 
to operate in a multitasking or non- 
multitasking environment. 

Entry point names are given additional 
letters alphabetically. The primary entry 
point (of resident library modules) is 
normally the link- edit name. Other entry 
points are named "B", "C", etc. For 
example, the primary entry point of the 
module with control name IBMBOCL is 
IBMBOCLA and the secondary entry point is 
IBMBOCLB.. 

The naming convention for conversion 
modules is slightly different. Arithmetic 
conversion modules have entry points 
indicated by a two-letter mnemonic code. 



The Multitasking Library 



The resident library is held on two data 
sets: sysl.PLIBASE and SYSl.PLITASK. 
SYSl.PLIBASE holds all modules that are 
needed to execute non-multitasking 
programs. SYSl.PLITASK holds the 
multitasking versions of all modules that 
differ for multitasking and non- 
multitasking environments. 

As explained above, both multitasking 
and non-multitasking modules have the same 
link- edit names for their entry points. 
Multitasking modules have a fourth letter 
T; non-multitasking modules have a fourth 
letter B„ in their control names. 

The U5se of the same link-edit name 
permits the compiler to generate the same 
code for library calls, regardless of 
whether the program is multitasking or non- 
multitasking. For multitasking programs, 
the data set SYSl.PLITASK must precede 



SYSl.PLIBASE in input to the linkage 
editor. In this way, the multitasking 
modules will be link-edited and the program 
will run in a multitasking environment. 
Further details of this arrangement are 
given in chapter lU. 



Library Workspace 



DSAs (dynamic storage areas) for certain 
library routines are no.t acquired in the 
same way as they are for source program 
subroutines. Instead of the storage being 
acquired from the LIFO stack, space is 
allocated, in the program management area, 
for two pre- formatted DSAs. These DSAs are 
known as levels of library workspace. 
Their format can be seen in figure 3.2. 
Library workspace (LWS) , provides a fast 
method for library routines to obtain DSAs. 
All the library routines have to do is to 
address the DSA and set the chainback 
field. There is no need to test to see if 
there is enough space for the DSA, as the 
space is already allocated. The NAB pointer 
does not have to be reset, because the next 
available byte is not changed. 

The PL/I libraries have been designed so 
that no more than two library modules 
require library workspace at any one time. 
This does not mean, however that no more 
than two library modules are ever active at 
any one time. Where more than two modules 
can be active, one or more of the modules 
will use a DSA in the LIFO stack. For 
conversion, a slightly different 
arrangement is used, whereby a DSA is 
acquired by the first module in the series 
and used by subsequent modules. This 
arrangement is described in chapter 10. 



FORMAT OF LIBRARY WORKSPACE 



Library workspace is designed so that 
either level can be treated by the 
housekeeping routines in the same way as a 
DSA. Chainback fields to the calling 
block's save areas are held in the head of 
library workspace and, where more than one 
level of library workspace is used, a 
chainback field is set up to the previous 
level. Figure 3.2 illustrates the method 
of chaining employed. 
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— ^ 


Flags 


Offset to ONCA 




Chain back field (to last DSA) 


Standard save area 












^ 


Address of next library worKspace 


Current NAB 


Workspace for library modules 




w 


Flags 


Offset to ONCA 




Chain back field 




' 








Standard save area 




Address of this level of LWS 

(used only when addressing the ONCA) 




Current NAB 




Workspace for library modules 




Current ONCA 


^ ^ 



1st level 



2nd level 



Figure 3,2. Library workspace 
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ALLOCATION OF LIBRARY WORKSPACE 



The Shared Library 



Library workspace is originally allocated 
within the program management area by the 
initialization routine IBMBPII. However, 
whenever an interrupt occurs and an on- unit 
is to be entered, a further two levels are 
allocated. This allows library modules to 
be called within an on-unit, without 
overwriting library workspace which may 
have been in use at the time of interrupt. 
Library workspace is acquired by a 
subroutine of IBMBPIR that is addressed 
from the TCA. 

Attached to each allocation of library 
workspace, including the initial allocation 
in the program management area, is an ON 
communications area (ONCA). This is a 
control block used in error handling to 
hold condition built-in function values. 
ONCAs are described fully in chapter 7. 



Library Modules and Weak External 
References 



Because of the modular structure of the 
library, a group of modules is frequently 
used to carry out some particular task, 
conversions, for example, are normally done 
by using a series of modules, and so are 
many of the mathematical built-in 
functions. For this reason, many library 
modules contain a number of external 
references to modules which may not be 
needed in a particular program. An example 
of this is shown in figure 3.3. To prevent 
unnecessary modules being link-edited, 
"weak external references" (WXTRNs) are 
used. WXTRNs are a special type of 
external reference designed to cater for 
this situation. 



Those entry points that are called only 
optionally are coded as WXTRNs. This 
prevents the linkage editor from loading 
these modules unless a separate external 
reference is made to them by the compiler. 
Thus the executable program phase does not 
contain modules that it never uses. 

Figure 3.3 shows part of a hierarchy of 
modules with alternative paths through 
them. When such a hierarchy exists, the 
actual path to be taken through the modules 
will be known to the compiler, and external 
references will be made to all the required 
modules whose names are coded as WXTRNs. 
The effect of this is that the linkage 
editor loads only the required modules. 



The shared^library is a PL/I facility that 
allows an installation to load PL/I 
resident library modules into the link- 
pack-area (LPA) so that they are available 
to all PL/I programs. This reduces space 
overheads. 

The modules to be included in the shared 
library can be chosen by the installation. 
They must include the initialization 
routine, the error handling routine, the 
open file routine, and all modules 
addressed from the TCA that are not 
identical for multitasking and non- 
multitasking programs. Further details are 
given in the publication OS PL/I Optimizing 
Q20!2i.i§£« System Information. 

The routines in the shared library are 
held in two of three link- pack- area 
modules: IBMBPSM, and either IBMBPSL or 
its multitasking equivalent IBMTPSL. Each 
of the link-pack modules contains a number 
of library routines, and is headed by an 
addressing control block known as a 
trans f6r_vec tor. IBMBPSM contains those 
modules in the shared library that are 
common to both multitasking and non- 
multitasking PL/I environments. IBMBPSL 
contains the non-multitasking versions of 
those modules that are not identical in 
multitasking and non-multitasking PL/I 
environments. This module has a 
multitasking counterpart, IBMTPSL, which 
holds the multitasking versions of such 
modules. 

Two further modules are also involved in 
handling the shared library. These are the 
shared library addressing modules IBMBPSR 
and its multitasking counterpart IBMTPSR (R 
stands for region) . One or other of these 
modules is link-edited with compiled code 
and held in the program region: IBMBPSR 
for non-multitasking programs, or IBMTPSR 
for multitasking programs, IBMBPSR and its 
multitasking counterpart hold dummy entry 
points which duplicate the names of all 
entry points of modules within the shared 
library. References to such entry points 
in compiled code are resolved to the dummy 
entry points in IBMBPSR or IBMTPSR. 

The situation during execution is as 
shown in figure 3.4. In the link-pack-area 
are two link-pack modules: IBMBPSM and 
IBMBPSL (or its multitasking counterpart) ; 
these contain all the routines in the 
shared library. In the program region is 
the shared library addressing module 
IBMBPSR (or its multitasking counterpart) . 
All references by compiled code to entry 
points in the shared library have been 
resolved by the linkage editor to IBMBPSR 
(or IBMTPSR). 



^t^ 



r 



IBMBSFi 



F-format input 
conversion director. 
Contains WXTRNs for: 
IBMBCCSA, IBMBCTHD, 
etc. 



< 



^ 



Figure 3.3. Example of use of WXTRNs 



IBMBCCS 

Special string conversion 
module. Contains WXTRNs for: 
IBMBCCAA, IBMBCACA, etc. 



IBMBCTH 



E- or F-format-to-arithmetic 
conversion module. Contains 
WXTRNs for: 
IBMBCEZX, IBMBCHZD, etc. 
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PROGRAM REGION 



Compiled code 



TCA 



L 



Dummy j 

IBMBCCAA A 




Pick up address of 
IBMBPSM from TCA" 



Pick up address at 
offset and branch. 



LINK PACK AREA 



IBMBPSM 



A(IBMBCCAA) 



IBMBCCAA 



The compiled code address 
constant for IBMBCCAA is 
resolved to the dummy 
IBMBCCAA in the module 
IBMBPSR. This dummy 
module picks up the address 
of IBMBPSM from the TCA, 
adds a known offset, and 
picks up the address held 
at this offset. This is the 
address of IBMBCCAA in 
the shared library link pack 
area. 



Figure 3.4. The shared library during execution 
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Program region 
IBMBPSRand IBMTPSR 



VCONs and WXTRNs for all 
modules that may be called 
from shared library but are 
not included in it. 



Dummy entry points for all 
modules in the shared library, 
followed by addressing code 
that passes control to the real 
modules. 



Transfer 
vectors 



Library 
routines 



Link pack area (shared library) 
IBMBPSL, IBMBPSM & IBMTPSM 





VCONs for all modules held 
in the shared library. 




Dummy entry points for all 
modules that may be called from 
the shared library but are held in 
the program region. These entry 
points are followed by addressing 
code that passes control to the 
real modules. 


r 


Individual modules in the 
shared library. 


S 
^•.^. 













Figure 3.5. The format of shared library modules 
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Communicationbetween Program Rec^ion 
and Link-Pack-Rrea 



Communication between the link-pack-area 
and the program region is handled by the 
transfer vectors that are held at the head 
of each module, communication is necessary 
in both directions. The compiled program 
will need to call library subroutines that 
are held within the link-pack modules in 
the link- pack-area. Similarly, certain of 
the modules in the link-pack-area may need 
to call modules that are not included in 
the shared library. 

The link-pack-area modules IBMBPSL and 
IBMBPSM, are headed by transfer vectors, 
which are followed by the individual 
library modules in the shared library. The 
individual modules and the transfer vector 
are link- edited to form one module when the 
shared library is created. The program 
region module IBMBPSR consists only of a 
transfer vector. (The format of the shared 
library modules is shown in figure 3.5.) 
During program initialization, the 
addresses of the three modules being used 
(and consequently the address of the 
transfer vector) are placed in the TCA. 

The transfer vectors contain three types of 
data: 

1. Dummy entry points for all modules 
that are not held in that area (i.e., 
the program region transfer vector 
contains dummies for all entry points 
that are held in the shared library; 
the link- pack transfer vector contains 
entry points for all modules that 
could be called from the shared 
library but are not included in it) . 

2. code# following the dummy entry 
points, that passes control from the 
dummy entry point in one area to the 
real entry point in another area. The 
code takes the form: 

L 15, offset (12) 

L 15, XXX (15) 

BR 15 

where "offset" is the offset to the 
address of the transfer vector in the 
TCA, and "xxx" is the offset within 
the transfer vector to the required 
address. 

3. An ordered list of addresses for all 
routines that are held in the same 
area as the vector. 

The code (item (2) above) transfers control 
in the manner shown in figure 3.5. 



1. It picks up the address of the 
relevant transfer vector from the TCA, 
where it was placed during program 
initialization. 

2. It picks up the address of the module 
it requires from a known offset from 
the start of the transfer vector, 

3. It branches to the address, thus 
passing control to the required 
library routine. 

The code does not use any register 
except register 15. The link register (14) 
is not altered, and control returns 
directly from the module to the caller. 



Execution when_JJsing the _ Shared Library 



Use of the shared library is specified by 
the linkage editor statement INCLUDE 
PLISHRE, PLISHRE is an alias for the 
program region modules IBMBPSR and IBMTPSR, 
The appropriate module will therefore be 
loaded by the linkage editor (IBMBPSR for 
non-multitasking programs; IBMTPSR for 
multitasking programs). All compiled code 
external references to shared library 
module entry points are then resolved to 
the dummy entry points in IBMBPSR (or 
IBMTPSR). Similarly WXTRNs in the program 
region module are resolved if compiled code 
issues an EXTRN for the entry point. 



Program, Initializatign 



At the start of the program, control is 
passed to one of the entry points of the 
initialization routine. This entry point 
will, in fact, be a dummy entry point in 
the shared library program region module. 
Each entry point is followed by code which 
requests the system to load the shared 
library link-pack modules. If the modules 
are already loaded, the system simply 
returns their addresses. If they are not 
loaded, it loads them into the link-pack- 
area, and then returns the addresses. 

The addresses of the two link- pack-area 
modules and of IBMBPSR are added to the 
parameter list for IBMBPIR. IBMBPIR is then 
called in the usual shared library manner, 
that is, via the transfer vector in one of 
the link-pack modules. 

It is the standard action of the 
initialization routines to load these 
parameters into the appropriate fields in 
the TCA. When the shared library is not in 
use, meaningless information is loaded into 
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PROGRAM REGION 



R12— *. 



TCA 



Compiled Code 



TPSR 



TPSL 



TPSM 




Program region module 
IBMBPSR or IBMTPSR 



Transfer vector 
Dummy entry 
points with 
duplicate names 
to all entry points 
in the shared 
library 




LINK PACK AREA 



Link pack module 
IBMBPSM 



Transfer vector 
Dummy entry 
points with 
duplicate names 
to all entry points 
called by shared 
library modules 
but not in shared 
library. 



Shared library 
routines. 



Link pack module 
IBMBPSLor IBMTPSL 



Transfer vector 
Dummy entry 
points with 
duplicate names 
to all entry points 
called by shared 
library modules 
but not in shared 
library. 



Housekeeping and 
environment 
dependant 
modules in the 
shared library. 



Figure 3.6. Addressing a module in the shared library 
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these fields. However, as they are only 
accessed by the shared library modules, 
this does no harm. 



program is link- edited. 



Initializing the Shar ed ^ Librar y 



The shared library is initialized by the 
use of special macro instructions, as 
described in the Sy st em I nfor m ation manual. 

All five modules must be created at the 
same time. During the process, the table 
of VCONs in the link-pack modules, transfer 
vectors are generated, and the offsets to 
these VCONs from the head of the transfer 
vector are placed in the code following the 
dummy entry points in the program region 
modules. A similar process is carried out 
for addresses in the program region. The 
VCONs within the link-pack modules are 
resolved by the linkage editor when the 
link- pack modules are created. The VCONs 
within the program region modules are 
qualified by WXTRNs, and are only resolved 
if compiled code generates an EXTRN for the 
entry point. Such EXTRNs are generated 
when required, as a normal part of the 
compilation process, regardless of whether 
the shared library is being used. The 
VCONs in the program region modules are 
resolved by the linkage editor when the 



Multitasking ConsideratiCMis 



The shared library has been designed so 
that multitasking does not affect it. If 
PLI.TASK is specified before PLI.BASE, the 
linkage editor statement INCLUDE PLISHRE 
will result in the module IBMTPSR being 
loaded and linked in the program region. 
When control passes to the code following 
the IBMBPIR entry point in IBMTPSR, a 
request is made to the system to load the 
multitasking shared library module IBMTPSM. 
The program then runs in the usual manner, 
with the multitasking modules. 

An installation can specify a shared 
library that includes only the multitasking 
or the non-multitasking modules. However 
both multitasking non-multitasking versions 
of the program region module will still be 
created. The module for the unwanted 
environment will be a dummy. This prevents 
problems should an INCLUDE PLISHRE 
statement be included in a program that is 
intended to run in the environment with no 
shared library. If this process was not 
carried out, such a statement could result 
in the incorrect environment being 
initialized. 
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Storage 



PL/ 1 Statement 
DCL TABLE (10) 
FLOAT DECIMAL (6); 



TABLE (0) 



TABLE (i; 



TABLE (9) 


TABLE (10) 


%t '-: -:" 'J ", 






; 



Short floating-point decimal 6 












WMMMJiil^ 



Address of TABLE 



Address of descriptor 



RV0=4 



Multiplier=4 



Upperbound-10 



Lowerbound=1 



Virtual origin 



Array TABLE (10) 



DED 



Aggregate locator 



Array descriptor 



*R\/0 (Relative virtual origin} is the offset of the actual 
origin of the array from the virtual origin (the position that 
element TABLE (0) would hold if it existed) 



Figure ^.1. Example of descriptor, locator, DED, and storage location of an array 
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Chapter 4: Communication Between Routines 



PL/I allows the programmer the choice of a 
large number of data attributes. Normally 
there is no need for explicit attribute 
information to be retained until execution, 
because the methods used to handle the data 
can be resolved during compilation. 
However, there are certain situations where 
this cannot be done. For example, 
adjustable bounds or extents may prevent 
the data attributes being fully known at 
compile time, or the data may be being 
passed to another PL/I procedure or library 
subroutine. When these situations arise, it 
is necessary to retain some or all of the 
data attributes in an explicit form 
throughout execution. 

The names of variables fall into a 
similar category. Normally, they need not 
be explicitly known during execution. 
However, for data-directed input/output and 
the CHECK condition, the names of the 
variables need to be known so that they can 
be associated with the correct values. 



An example of the way in which data is 
related to its locators, descriptors, and 
DEDs is given in figure 4.1. 



Notes on Terminology 



The following terms are used in this 
chapter . 

Virtual origin (VO) The address where the 

element of an array 
whose subscripts are 
all zero is held or, if 
such an element does 
not appear in the 
array, where it would 
be held. 



Actual origin (AO) 



The address of the 
first item in the array 
or structure. 



When such information must be retained 
until execution, special control blocks are 
set up for the purpose. These control 
blocks are described in this chapter. 

The control blocks are: 

Descriptors; These hold the extent of the 
data item (i.e., string lengths, array 
bounds, and area sizes). 



Relative virtual 
origin (RVO) 

Structure element 



Base element 



Actual origin minus 
virtual origin. 

A minor or major 
structure that contains 
a number of base 
elements. 

A data element or array 
within a structure. 



Locators; These hold the address of a data 
item and, if they are not concatenated with 
the descriptor, hold its address. 

Descriptor Descriptors; These hold the 
logical structure levels, dimensions, and 
lengths, of all elements within a 
structure . 

Dat a_E lement_Des cr igt grs __( DEDs )_ : These 

hold the attributes of a variable required 

for data manipulation, except for extents, 
which are held in descriptors. 

Symbol, Tables ; These hold the names of the 
variables and associate them with the 
appropriate storage locations during 
execution . 

Sy!Sbol__Table_Vector: This associates 
symbol tables with the block in which they 
are known. 

Descriptor/Locator ; This is a term used to 
describe the control block consisting of a 
descriptor concatenated with a locator. 



DESCRIPTORS AND LOCATORS 



Descriptors are generated when adjustable 
extents are involved, or when an item is to 
be passed as an argument and the associated 
parameter is the type that can be declared 
with an asterisk among its attributes. For 
example, DCL X CHAR (N) ; or DCL X CHAR (♦) ; 
would both result in the generation of a 
descriptor, in the first case, code for the 
SUBSTR built-in function would have to be 
interpretive if STRINGSIZE were enabled. 
The appropriate library module would be 
called, and it would make use of the 
descriptor to discover the length of the 
string. This length would have been placed 
in the descriptor by the prologue code of 
the block in which the string was declared. 
In the second case, where the length of the 
string is signified with an asterisk, the 
program that is passed the string will 
expect to receive the length of the string 
in a descriptor. 
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Name of: control block 



Conditions under which it is 
generated 



Location 
(control section) 



Data element descriptor (DED) 



Array descriptor 



Aggregate locator 



Area locator/descriptor 



String locator/descriptor 



Structure descriptor 



Aggregate descriptor 
descriptor 

Symbol table 



Symbol table vector 



When conversion or stream I/O library 
modules are called. 

When an array has adjustable bounds 
or may be passed to a library 
subroutine or other PL/I routine. 

When structure or array descriptor is 
generated. 

When an area is declared with an 
adjustable size or may be passed as 
an argument. 

When a string is declared with an 
adjustable length or is passed as an 
argument. 

When a structure is declared with 
adjustable elements or is passed as 
an argument. 

When a structure contains elements 
declared with adjustable bounds. 

When an item may appear in 
data-directed I/O or in a 
CHECK list 



When GET DATA or PUT DATA is used 
without a data list, or when SIGNAL 
CHECK is used without a data list. 



Static internal 



Static internal 



Static internal 



Static internal 



Static internal 



Static internal 



Static internal 



Static internal 
for internal 
items. Separate 
CSECT for 
external items. 

Static internal 



Figure 4.2. Descriptors, locators, and symbol tables: when generated, where held 



Data items that can be declared with an 
adjustable value or an asterisk are: 
string lengths, array bounds, and area 
sizes. Descriptors are, therefore, needed 
for strings, arrays, and areas. They are 
also needed for structures, because 
structures can contain strings, arrays or 
areas. 

In order to connect the data with its 
descriptor, a further control block is 
generated. This is the locator. The 
locator addresses both the descriptor and 
the variable. For strings and areas, the 
locator is concatenated with the descriptor 
and contains only the address of the 
variable. For structures and arrays, the 
locator is a separate control block and 
holds the address of both the variable and 
the descriptor. Called routines are 
normally passed the addresses of locators, 
rather than the addresses of arguments when 
arguments requiring descriptors are passed. 

When the descriptor and locator are not 



concatenated, it is possible to use the 
same descriptor for a number of different 
data items, provided that these items have 
the same attributes. This process is known 
as "commoning* and is used to conserve 
space. Where possible, the compiler 
commons structure and array descriptors and 
aggregate descriptor descriptors. 

Except for controlled variables, 
descriptors and locators are always held in 
the static internal control section, 
regardless of the attributes of the data 
that they describe. 

For controlled variables, the descriptor 
and, sometimes, the locator are held 
immediately before the data. (For details 
see •controlled Variable Control Block* in 
appendix A) . 

The following types of descriptor and 
locator are generated. Figure U.2 
summarizes the conditions under which they 
are generated and gives their storage 
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locations. In the main, they are set up 
during compilation and completed during 
execution, if necessary. 



§t£iQ3_Ii2£§tor/Descri2tor 



The string locator/descriptor holds the 
byte address of the string, information on 
whether or not it is a varying string, and 
the maximum length of the string. For a 
bit string, the bit offset from the byte 
address is held. (See figure 4.3.) 



Area Locator/Descriptor 



The area locator/descriptor holds the 
address of the start of the area and the 
length of the area. (see figure 4.4.) 



Aggreqate Locator 



The aggregate locator holds the address of 
the start of the array or structure and the 
address of the array descriptor or 
structure descriptor. (See figure 4.5.) 



Array Pes cr iptor 



The array descriptor holds: 

1. The relative virtual origin (RVO) of 
the array. This is the offset of the 
start of the first element in an array 
(actual origin) from the virtual 
origin. The virtual origin (VO) is the 
point at which element (0) would be 
held in a one-dimensional array, 
element (0,0) would be held in a two- 
dimensional array, etc. in a one- 
dimensional array, the address of any 
particular element can b6 discovered 
by multiplying together the subscript 
and the multiplier (see below) and 
adding the result to the virtual 
origin of the array. An extension of 
this method is used for multi- 
dimensional arrays, the formula being: 

Address of element (Si,S3, . . .,Sn) 

n 

= VO+y^(Mi*Si) 
where S is the subscript number, and 



M the multiplier, of the ith 
dimension, and VO is the virtual 
origin. 

For unaligned bit- string arrays, the 
virtual origin points to the byte 
address before the element (0). The 
bit offset is held in the string 
descriptor, which is concatenated with 
the array descriptor. 

2. The high and low bounds for the 
subscripts in each dimension. 

3. The multiplier for each dimension. 
The multiplier is the distance between 
the start of one element and the start 
of the next element in the same 
dimension. For example in the array 
declared A(2,2), the multiplier for 
the first dimension is the distance 
between the start of element A (1,1) 
and the start of element A (1,2). 

When the array is an array of strings or 
areas the string or area descriptor is 
concatenated with the end of the array 
descriptor to provide the necessary 
additional information. Array descriptors 
are commoned where possible. That is, one 
descriptor is used for a number of similar 
arrays. 



Structure_Descriptor 



The structure descriptor consists of a 
series of fullwords, giving the byte offset 
of the start of each base element from the 
start of the structure. If a base element 
has a descriptor, the descriptor is 
included in the structure descriptor, 
following the appropriate fullword offset. 
Where a bit offset is involved, this will 
be held in the descriptor for the bit 
string, or in the relative virtual origin 
if the item is a bit string array. 

A structure must be mapped during 
execution if any of the elements in the 
structure have adjustable bounds or 
extents, or if the REFER option is used. 
Where possible, structure descriptors are 
commoned. That is, one descriptor is used 
for a number of similar structures. If a 
structure or an array of structures 
contains elements with adjustable extents, 
the structure descriptor is not set up 
during compilation. Instead, it is set up 
during execution from information held in 
the structure descriptor descriptor. (See 
below for information on arrays of 
structures and structtires of arrays.) 
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1 



Byte address of string 



Length 



Unused 



Bit offset 



\- 



For varying strings, the maximum Ofixed length For bit strings only 

length is held 1=varying length 



Figure 4., 3. String locator/descriptor 



Address of first byte of area 



Allocated length of area (in bytes) 



Figure 1.4. Area locator/descriptor 



Byte address of first byte of aggregate 



Address of array or structure descriptor 



Figure 4.5. Aggregate locator 



1 






2 3 


4 


RVO (Relative virtual 


origin) 






M, (multiplier) 


U, (upperbound) 


Li (lowerbound) 


1 ' 
t 1 


Mn 


u„ 


Ln 



Notes: 1. For unaligned bit strings, RVO and multiplier are bit values. 

2. For strings and areas, the area or string descriptor is concatenated 
to the end of the array descriptor. 

Figure U.6. Array descriptor 



Multiplier and bounds 
for 1st dimension 



Multiplier and bounds 
for nth dimension 
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When a structure cannot be mapped during 
compilation, more information than is held 
in the structure descriptor is needed for 
it to be mapped during execution. This 
information is held in a control block 
known as an aggregate descriptor 
descriptor. 

The information held in an aggregate 
descriptor descriptor is the number of 
dimensions and logical level of all the 
structure elements, and the number of 
dimensions, logical level, and alignment 
requirements, of all base elements, plus 
the length of those base elements that do 
not have their" length held in descriptors, 
(strings and areas, and arrays of strings 
and areas, have their lengths in 
descriptors.) The length held for an array 
is the length of an array element. The 
total length of the array can be calculated 
by using the information in the array 
descriptor. 

The aggregate descriptor descriptor is 
set up in static internal storage and is 
set up completely during compilation. The 
format is shown in figure 4.7. An example 
showing the method used to map a structure 
that contains an element with an adjustable 
extent is shown in figure 4.8. 

Where possible, aggregate descriptor 
descriptors are commoned. 



Arrays of structures and Structures of 

Arrays 

Where necessary, an aggregate locator, a 
structure descriptor, and an aggregate 
descriptor descriptor are generated for 
both arrays of structures and structures of 
arrays. 

The structure descriptor for both an 
array of structures and a structure of 
arrays has the same format. The difference 
is in the values in the fields of the array 
descriptors within the structure 
descriptor. Take for example the array of 
structures AR and the structure of arrays 
ST, declared below. 

Array of . Structures structure of Arrays 



DCL 1 AR(IO) , 
2 B, 

2 C; 



DCL 1 ST, 

2 B(10), 
2 C(10); 



The structure descriptor for both AR and 
ST would contain an offset field for both B 
and C and an array descriptor for both B 



and C. (See figure 4,9.) However, the 
values in the descriptors would differ, 
because the array of structures AR would 
consist of elements held in the order 
B,C,B,C, etc., and the elements in the 
structure of arrays ST would be held in the 
order: 

B,B,B,B,B,B,B,B,o,D,C,C,C,C,C,C,C, €.,(-,([.. 



DATA ELEMENT DESCRIPTORS 



When data is passed to the PL/I library 
routines, a complete description of the 
data is frequently required, and something 
more than a descriptor is therefore needed. 
Conversion routines, for example, need to 
know the complete attributes of the data. 
To hold such information, data element 
descriptors (DEDs) are generated. (Control 
blocks known as DEDs are also used by the 
compiler. These are compile-time DEDs and 
have a different format from those that are 
used during execution. Compile-time DEDs 
never appear in the executable program. ) 
For stream I/O, DEDs are generated to 
describe the format of the input or output. 
These DEDs are known as format element 
descriptors (FEDs). 

DEDs are produced for all types of 
variable or temporary that are passed to 
the library for conversion or stream 
input/output. The length and format of the 
DED depends on the data type of the item. 
DEDs are shown in detail in appendix A. An 
indication of their format is given in 
figure 4.10. 

DEDs are always held in static internal 
storage. They are used only to pass 
information to library routines. 

There are five types of DEDs: 
arithmetic DEDs, arithmetic pictured DEDs, 
string DEDs, pictured string DEDs, and 
FEDs. 

Arithmetic DEDs: are 4 bytes long. 

Arithmetic .pictured DEDs; (always decimal) 
are 8 bytes plus picture specification, 
which consists of at least one byte for 
every character in the pictured string. 
Maximum length for pictured arithmetic DEDs 
is 264 bytes. 

String_DEDs: are 4 bytes long. 

Pictured _st ring J3EDS : (always character 
string) are six bytes plus the picture 
specification, which consists of one byte 
for every character in the picture string. 
The maximum length for pictured character 
DEDs is 261 bytes. 
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1 



Structure 



Offset (fullword 



, Offset of entry for containing structure from 
start of ADD (all ones for a major structure) 



0=structure 
1=base element 



O=not bit string 
1=bit string 



Level 



\ 



Dimension 



l=last element 
O=not last element 



1 =area 
O=not area 



Alignment 



7 



Length (bytes) 



Base element 



0=bit 
7=byte 

15=halfword 
31=fullword 
63=doubleword 



All zero for areas and strings 



There is a fullword entry in the ADD for each structure (major and minor) and each base element. 



Figure 4.7. Aggregate descriptor descriptor 
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DURING COMPILATION 



DURING EXECUTION 



■\ Space tor structure descriptor allocated in static 
storage. 

2 Aggregate descriptor descriptor allocated, and 
fields filled in from structure declaration. 

3 Aggregate locator allocated, and address of 
structure descriptor place in second word. 
Code is generated within the prologue of the 
block in which the structure is declared to call 
structure mapping routine, IBMBAMM, to 
acquire a VDA, and to complete the aggregate 
locator. 



Prologue code places value of N(1 byte) in 
the string descriptor for D in structure 
descriptor. 

IBMBAMM is called to map the structure, 
using the information in the ADD and the 
SD (which contains the length of element 
D). D is aligned with E, then B is aligned 
with DE. (The rules for structure mapping 
are given in the language reference manual 
for this compiler.) The results of the 
nnapping are placed in the structure 
descriptor, 

IBMBAMM returns the length of the 
structure to compiled code, which acquires 
a VDA for the structure and places the 
address of the structure in the aggregate 
locator. 



THE RESULT 

Every member of the structure can be addressed by 
means of the address in the aggregate locator and 
the offsets within the structure descriptor. When bit 
offsets are involved, they are contained within the 
appropriate descriptor in the structure descriptor. 



DURING COMPILATION 

SD 1 



DURING EXECUTION 
SD 5 



Space for offset of B 



Space for offset of D 



Space for descriptor of D 



Space for offset of E 



Zero 



1 byte 



ADD 






2 






01 


All ones 


Level 1 


00 


Zero 


10 


X'31' 


X'4' 


Level 2 


00 


Zero 


00 


Zero 


Level 2 


00 


Zero 


10 


X'7' 


Zero 


Level 3 


00 


Zero 


11 


X'31' 


X'4' 


Level 3 


00 


Zero 



ADD is unchanged during execution. 



For meaning of en tries, see Figure 4- ■ 7. 



AL 



Space for address of structure 



Address of structure descriptor 



Declaration 

DCL 1 A, 

2 B FLOAT, 

2 C, 

3 D CHAR(N), 
3 E FLOAT; 





AL 6 






Address of structure 




Address of structure descriptor 






»/DA for structure 6 






B 




^^^^^^H 


D 




E 





Figure 4.8. Example of handling a structure containing an adjustable extent 
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Array of structures 

DCL 1 AR(IO), 
2B, 
2C; 



Structure of Arrays 

DCL 1 ST, 

2 8(10), 
2C(10); 



AR.B 



AR.C 



Structure descriptor for AR 



Offset = 



RV0 = 8 



Multiplier = 8 



Upperbound = 10 



Offset = 4 



RV0 = 8 



Multiplier = 8 



Upperbound = 10 



Lowerbound = 1 



Lower bound = 1 



Structure descriptor for ST 





Offset = 


ST.B 


RVO = 4 


Multiplier = 4 




Upperbound = 10 


Lowerbound = 1 




Offset = 40 


ST.C 


RVO = 4 


Multiplier = 4 




Upperbound = 10 


Lowerbound = 1 



Note: Descriptors are identical apart from multiplier RVO offset values 



Figure U.9. Structure descriptor for arrays of structures and structures of arrays 
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l!15s_linE!it/outgut_DEDs )_ : 
classes 



fall into five 



1. A,B, and control format FEDs have four 
bytes. 

2. E and F format FEDs are six bytes 
long. 

3. Pictured arithmetic FEDs consist of 
four bytes followed by the pictured 
arithmetic DED. 

4. Pictured character string FEDs consist 
of four bytes followed by the pictured 
character string DED. 

5. C format FEDs are four bytes plus the 
two constituent FEDs that make up the 
complex item. They are used for 
complex data. 

The first two bytes of any DED are the 
look-up byte and the flag byte. Taken 
together, they define the data type and 
permit a receiving routine to determine if 
it needs to look further into the DED for 
more information. The general format of 
DEDs is shown in figure 4.10. Full details 
are given in appendix A. 



SYMBOL TABLES AND SYMBOL TABLE VECTORS 



Data-directed I/O statements, and the CHECK 
condition, require the names of variables 
to be available throughout execution. 
Normally, such names are not used after 
compilation. When required during 
execution, these names are held in control 
blocks known as symbol tables. Symbol 
tables hold the name of the variable, its 
address, and the address of its DED plus 
certain other information (see appendix A). 



GET DATA and PUT DATA statements without 
a data list, and SIGNAL CHECK statements 
when there is no check list, imply that the 
names of all variables known at that point 
in the program must be available. The 
necessary information is held in a further 
control block known as the sYmbol_table 
vector. The symbol table vector holds the 



addresses of symbol tables arranged in 
order of program blocks, commencing with 
the main procedure block. The symbol table 
vector consists of a series of fullword 
fields. These fields contain either the 
address of a symbol table, a fullword of 
zeros, or a further address within the 
symbol table vector. The end of entries 
for variables declared in each block, is 
followed by a fullword of zeros, which in 
turn is followed by the address in the 
symbol table vector where entries for the 
encompassing block begin. If there is no 
encompassing block, another word of zeros 
marks the end of the vector. 



Figure 4.11 shows the relationship 
between variables, symbol tables, and the 
symbol table vector. 



Data-directed I/O modules, and the CHECK 
module, use symbol tables and symbol table 
vectors in the following ways. 

GET DATA (A,B,C)^ PUT DATA (A^B,C), SIGNAL 
CH ECK_ J^Aj_BjlC )_ : In all these cases, the 
addresses of the symbol tables for A, B, 
and C are passed to the appropriate library 
module. 

GET DATA, PUT DATA, SIGNAL CHECK; When no 
data or check list is included in the 
statement, the library is passed the 
address of the start of the associated 
block entries for the symbol table vector. 
By following the symbol table vector, it is 
possible to access the names of all the 
variables known in the block. 

The contents of symbol tables vary 
according to the storage class of the 
variable. The method used for holding the 
address, and other information, is given in 
appendix A. For internal variables, symbol 
tables are held in static internal storage. 
For external variables, symbol tables are 
held as separate control sections in static 
external storage. The name of each control 
section is the name of the associated 
variable followed by an X. Thus the 
control section for the external variable B 
would be BX. Such a control section would 
also contain the DED of the variable (or 
DEDs if the variable was a structure) . 
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String DED 



Look-up byte 


Flag byte 


Not used 



Arithmetic DED 



Look-up byte 


Flag byte 


Precision 


Scale 



Pictured string DED 



Look-up byte 



Flag byte 



Length of string 



Length of string without/insertion characters 



Translation of picture 



specification into internal format (one byte per character) 



Pictured arithmetic DED 



Look-up byte 


Flag byte 


Precision 


Scale 


Length of picture 


Length of data 


Mantissa byte 


Exponent byte 


Translation of picture specification into internal format (at least one byte per character) 


^ 



Figure U.IO. Format of DEDs 
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PROGRAM BLOCK STRUCTURE 

Main procedure 



DCL A, B, C; 



Subroutine 1 
DCL X, Y, A; 



Subroutine 2 
DCL X, Y; 



Vector for 
main procedure 



Vector for 
subroutine 1 



Vector for 
subroutine 2 



^ 


Symbol table vector 


k. 


Symbol tables for: 


w 


A 


A in main procedure 




B 


B in main procedure 


w 


C 


C in main procedure 




00000 




00000 




X 


X in subroutine 1 




Y 


Y in subroutine 1 


w 


A 


A in subroutine 1 




00000 




- Pointer 




X 


X in subroutine 2 




Y 


Y in subroutine 2 


w 


00000 




- Pointer 





The symbol table vector is built up on a block by block basis, the last entry for each block being a word of 
zeros followed by a pointer to the first entry for the encompassing block. This mechanism allows for 
multiple declarations of names. 

Figure 4,11. Symbol tables and symbol table vectors 
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PLISTART 



Receives control from 
system 



Initialization routines 



Set up TCA, initialize storage and 
issue SPIE & STAE to initialize 
PL/I error-handling scheme. Pass 
control to the address in 
PLIMAIN. 



Prologue code 



Acquires DSA for main 
procedure, initializes 
control blocks, etc. 



Functional code 



Carries out function required 
in source program. This 
usually involves calls to 
library subroutines. 



Epilogue code 



Restores IBMBPIR's 
registers 



Termination routines 



Closes any files still open and 
returns control to system 



Figure 5.1. Flow of control during execution 
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Chapter 5: Object Program Initialization 



Before the output from the compiler can be 
executed, it must be link-edited, and the 
PL/ I environment must be set up. This 
chapter briefly describes the effects of 
link-editing, the manner in which the 
program is entered, and the initialization 
process that sets up the PL/I environment. 
Initialization for multitasking programs is 
explained in chapter 14. it also gives a 
brief description of the program management 
area; a control area set up during program 
initializ ation. 



Link-editing 



The functions and use of the linkage editor 
program are described in the publication OS 
liiQli§L3§_Editor_and_Loader. This chapter 
describes the effects of link-editing on 
the PL/I program. The linkage editor 
combines the various control sections 
generated by the compiler and resolves 
addresses within these control sections. 
The linkage editor also incorporates into 
the executable program phase all library 
modules that are called from compiled code, 
and a number of other library modules that 
are required either because they in turn 
are called by the library modules called by 
compiled code, or because they are needed 
for program management. A major module 
used in program management is the error- 
handling module, IBMBERR. An external 
reference to this module is contained in 
the PL/I initialization routine, IBMBPIR. 
An external reference to IBMBPIR is 
included in the control section PLISTART 
which is generated by every compilation and 
nominated as its entry point. PLISTART 
contains an external reference to the 
control section PLIMAIN (which holds the 
address of the start of the main 
procedure) . 

One of the features of the linkage 
editor is that it does not accept more than 
one control section with the same name; the 
second use of the name is ignored. As a 
result of this, only one PLISTART and one 
PLIMAIN is generated for each executable 
program phase. This allows two or more 
PL/I main procedures to be link-edited 
together. The procedure that receives 
control will be the first that is passed to 
the linkage editor, because it will be the 
PLISTART and PLIMAIN of this procedure that 
are included in the executable program. 
This feature is also used to handle data 
declared EXTERNAL. Control sections for 



each such data item are generated by all 
programs in which the data is declared. 
Only one of these is resolved. 

Note: The entry statement cannot be used 
to pass control to a specified PL/I program 
as entry must be made through PLISTART. 

The PLIMAIN control section is not 
generated by the compiler if the PL/I 
source program does not contain the MAIN 
option. However, a control section named 
PLIMAIN is included in the initialization 
module IBMBPIR. This control section 
contains the address of code that calls the 
module IBMBPEP, which puts out a message 
saying there is no main procedure, after 
which the program is terminated. 



Program Initialization 



code is compiled by the PL/I Optimizing 
Compiler on the assumption that various 
control blocks will have been set up and 
that certain registers will point to them 
when the program is entered. This 
arrangement of control blocks and registers 
is known as the PL/I environment. 

The most important factors affecting the 
PL/I environment are the following: 

1. An area for the allocation of PL/I 
dynamic storage should be available. 
This area is known as the initial 
storage area (ISA) . 

2. A dynamic storage area (DSA) should 
exist. This will give the address of 
the start of the area available for 
dynamic storage allocation and will 
act as a save area for the calling 
routine's registers. 

3. A task communications area (TCA) 
should exist. The TCA acts as a 
central communications area for the 
program, holding addresses of various 
storage- and error-handling routines, 
and control blocks. The TCA also 
contains a number of flags and other 
fields. 

4. Program checks should be passed to the 
PL/I error-handling module IBMBERR. 

5. Pre-f ormatted DSAs should exist for 
certain library routines. These pre- 
formatted DSAs are known as library 
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workspace (LWS) . 

A space should be available for any 
condition built-in function values 
(ONCHAR, ONSOURCE, etc.) Should a 
PL/I interrupt occur. This space is 
known as an ON communications area 
(ONCA) . As the condition built-in 
functions have default values, an area 
to hold the default values is 
required. This is known as the dummy 
ONCA. 



The resident routine, IBMBPIR, is a 
short control routine. The major functions 
are carried out by the transient routines. 
However, IBMBPIR contains a number of 
housekeeping subroutines, including code to 
handle GOTO out of block in certain 
abnormal situations, and the STAE exit 
subroutine. These are described in chapters 
6 and 7 respectively. 



7. Register 12 should point at the TCA, 
and register 13 should point to the 
DSA. 

The resident program initialization 
routine IBMBPIR,, and the transient routine 
IBMBPII, which it calls, acquire the ISA, 
and set up the various control blocks in an 
area of the head of the ISA known as the 
program management area. The contents of 
the program management area are described 
later in this chapter. 

I The default ISA size and other options 
I are controlled either by the system default 
I module IBMBOPT or by specifying an external 
variable called PLIXOPT within the program. 

The use of initialization routines 
obviates the need for special code in main 
procedures, and allows two procedures with 
the MAIN option to be used in the same 
program. 

As shown in figure 5.1, the 
initialization routine IBMBPIR is reentered 
after the execution of compiled code. This 
is done by the standard action of the 
epilogue code. The registers of IBMBPIR 
are stored in the dummy DSA by the prologue 
code, and restored by the epilogue code. 
When terminating the program, IBMBPIR calls 
a transient library routine, IBMBPIT, to 
handle the majority of the termination 
functions . 



INITIALIZATION AND TERMINATION ROUTINES 

Three routines are used in initialization 
and termination. They are: 

1. IBMBPIR - resident library 
initialization/termination routine. 

2. IBMBPII - transient library 
initialization routine. 

3. IBMBPIT - transient library 
termination routine. 

The use of transient routines reduces 
the space overhead required. 



Rgsident_lnitializatign/Terminat 
Routine"'lBMBPIR ~ 



IBMBPIR has three entry points. One of 
these is for use by the supervisor; the 
other two are for use by problem programs 
written in languages other than PL/I. The 
main difference between the entry points is 
the parameters that are expected. The 
entry points are: 

1. IBMBPIRA - used when entry is made 
from fhe system. 

2. IBMBPIRB - for use by non-PL/I callers 
who wish to accept PL/I default ISA 
size. 

3. IBMBPIRC - for use by non-PL/I callers 
who wish to nominate the length and, 
optionally, the address of dynamic 
storage used by PL/I. 

Entry points B and c will be used by 
programmers specifying PLICALLA and 
PLICALLB respectively. (PLICALLA and 
PLICALLB are entry points in the control 
section PLISTART.) Using PLICALLA results 
in control being passed to IBMBPIRB. Using 
PLICALLB results in control being passed to 
IBMBPIRC. 

IBMBPIRA and IBMBPIRC can be passed a 
number of parameters related to program 
management. These include ISASIZE and 
REPORT. IBMBPIR assumes that all parameters 
preceding a slash (/) are program 
management parameters. All main procedure 
parameters must, therefore, be preceded by 
a slash, otherwise they are taken to be 
parameters for IBMBPIR. 

Entry point IBMBPIRC can be passed a 
parameter list that contains (in the second 
and third words) the length and, 
optionally, the address at which the ISA is 
to begin. The ISA size and address are 
passed to IBMBPII. 

Entry point IBMBPIRB cannot accept any 
parameters; the default ISA size is always 
given. (See below, under the heading 
"Acquiring the ISA.") 
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R12 



Rt3 



MAS 



PROGRAM MANAGEMfcMT ARE A 



TCA 

Task GomrTKinicatJons area. 
See text and appendix A 



TCA Appendage 
See text and appendix A 



Dummy ONCA (ON cemmunicatiom area) 

Holds default vaJues for condition built-in functions 



TRT TabJe 

Translate-and-test tab\e for IBMBERR, used in error 
handling to test for relevant on-cells. 



Diagnostic Fite Biock 

Contains information relating to the use of SYSPRINT 
for the transmission of diagnostic messages 



Dump Block (DUB) 

Block used to access the dump file 



Ordered delete list 

Used to hold a list of transient modules to be deleted 
durir^ program termination 



Dummy task varia^e 

Used in tasking if no task variato+e is declared 



Save area for ISMBP6R 

Used by storage management routines when new 
segment of stora^ is required. 



Durrmiy DSA (Dyitamic storage area) 

Contains DSA for initialization routine, backchain 
to calling routine's save area (if any), pointer to 
start of major free area (NAB), etc. 



LWS (Library werkspace) 

Two Preformatted QSAsfor use by certain library routines 



ONCA 

Space in which condition built-in function valu'es 
are placed after an interrupt. 
Backchain points to dummy ONCA 



One unu^d word 



PRV entry for SY^R*NT 

At ftx»d negative offset to aJlow f0r fetched programs 



Pseudo Register Vector 

Control block used in addressing files and controlled 
variables. 




Figure 5.2. Frog^raai iRanafentent area 
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The_Process _of_Initializatign 

When IBMBPIR is called to initialize the 
program, it acquires workspace, then loads 
and calls IBMEPII. IBMBPII carries out the 
actions described below. 



Handling Execution Time Options 



IBMBPII first analyzes the execution time 
options. Execution time options, which 
were also known as program management 
parameters, can be specified in the 
following three ways: 

1. As parameters of the EXEC 
statement, 

2. From an external variable called 
PLIXOPT in the PL/I program. 

3. From the default module IBMBXOPT 
which is set up during compiler 
generation. 

All three sources may exist and the options 
are merged from them. IBMBPII first loads 
the default module IBMBXOPT. It then 
searches for a control section called 
PLIXOPT which will have been produced by 
the compiler if an external variable called 
PLIXOPT was declared in the program. Any 
options specified in PLIXOPT are then 
merged with those in IBMBXOPT with the 
values in PLIXOPT overriding those in 
IBMBXOPT. The process is then repeated 
with any execution time options specified 
in as parameters in the EXEC statement. 
When the execution time options have been 
sorted out, IBMBPII carries out the actions 
described below. 



Acguiring_the_ISA 



The method of acquiring storage for the ISA 
depends on the entry point of IBMBPIR used. 

If entry point C is used,, and both the 
ISA size and address have been passed, no 
further action need be taken. 

If the ISA size has been passed, to 
either entry point C or entry point A, a 
GETMAIN macro is issued for the amount of 
storage requested. 

If no ISA size has been specified, the 
default action is taken. The default 
action is to obtain all the available 
storage. The high-address half of this 
storage is then freed, and the lower half 



retained as the ISA. If the resulting 
figure is not large enough to hold the 
program management area, an area large 
enough for the program management area is 
obtained. 

If there is not enough space for the ISA 
size requested, or if the defaults do not 
provide enough space for the program 
management area, the action described below 
under the heading "Error Situations" is 
taken. 



Initialization of _the_,Prograro 
Management Area 



The program management area is set up at 
the low address end of the ISA. IBMBPII 
initializes the various control blocks. 
These are shown in figure 5.2. Their 
functions are described below under the 
heading "The Program Management Area. " 

The storage management routine is 
loaded, and the addresses of its various 
entry points are placed in the TCA. If a 
storage report is requested, module IBMBPGD 
is loaded; otherwise, module IBMBPGR is 
loaded. 



Initializing „PL/I JError Handling 



The PL/I error handling scheme handles all 
program checks, and attempts to handle 
ABENDS. The address of the old PICA is 
saved in the TCA so that the previous SPIE 
may be -restored during program termination, 
and SPIE and STAE macro instructions are 
issued to set up the PL/I error handling 
scheme. 

The SPIE macro specifies entry into 
entry point A of the error handling module 
IBMBERR. The STAE macro specifies entry 
into the STAE exit subroutine in IBMBPIR. 
(This subroutine loads the ABEND analyzing 
module IBMBPES.) A full description of the 
PL/I error handling facilities is given in 
chapter 7. 

When the program management area has 
been initialized, and the SPIE and STAE 
macro instructions have been issued, 
IBMBPII returns control to IBMBPIR. 

IBMBPIR checks that the return has been 
normal and, if so, points register 1 at the 
parameters for the main procedure, and 
calls the procedure whose address is held 
in the control section PLIMAIN. 



NOSPIE and NOSTAE 



If NOSPIE is 
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specified in the parameters passed to 
IBMBPIR no SPIE macro is issued by the 
initialization routine. This allows an 
installation to specify its own method of 
handling program check interrupts, 
similarly if NOSTAE is specified a STAE 
macro will not be issued. 



Error Situations 



THE PROGRAM MANAGEMENT AREA 



A diagram of the program management area is 
shown in figure 5.2. It shows the 
situation when the compiled program is 
called. The various fields in the program 
management area are shown in detail in 
appendix A. A brief description of their 
use is given below. 



If there is insufficient storage available 
to meet the requested ISA size, IBMBPII 
calls IBMBPEP, which puts out an 
"INSUFFICIENT MAIN STORAGE" message. 
IBMBPII then returns to IBMBPIR, requesting 
it to free the storage acquired, and 
terminate the program. 

If no PL/I main procedure has been 
provided, and there is no alternative 
PLIMAIN control section provided by the 
user, a control section PLIMAIN in IBMBPIR 
will have been link-edited. When control is 
passed to the address contained in this 
control section,, an error module is called. 
A 'NO MAIN PROCEDURE' message is generated, 
and the program is terminated. 



The Process of Termination 



When the main procedure is complete, 
epilogue code for the main procedure 
returns control to IBMBPIR, passing to it 
the address of the main procedure DSA. If 
the termination is normal, IBMBPIR restores 
the value of register 13 to that passed to 
it in register 0. IBMBPIR then sets flags 
in the TCA indicating that the program is 
terminating, and calls the error handler to 
raise the FINISH condition. If there is no 
GOTO from a FINISH on-unit, the error 
handler will return to IBMBPIR using the 
GOTO-out-of -block mechanism. The flags set 
in the TCA to indicate program termination 
are tested and, as they are set, control is 
returned from the GOTO code in the TCA to 
the abnormal-GOTO subroutine in IBMBPIR. 
This routine handles any outstanding 
housekeeping problems. Exit DSAs are 
correctly terminated and, because the 
program termination flags are set, all 
files are closed by calling IBMBOCL. 
Control is then returned to the termination 
routine, IBMBPIR. (A full discussion of the 
GOTO-out-of -block mechanism and its 
implications is given in chapter 2.) 

IBMBPIR then calls IBMBPIT to complete 
the housekeeping. STAE and SPIE macro 
instructions are issued to restore the 
error handling situation, and control is 
returned to the caller. 



T^slS_CQmmunicatigns_Area_XTCA)^ 

The TCA is the central communications block 
used throughout the program. It is used to 
address the error-handling and storage- 
management routines, and to point to the 
current segment of dynamic storage. 

A field-by-field description follows. 

Flags Indicate that an abnormal 
GOTO out of block may take 
place (see below) . Also 
indicate that certain special 
error conditions may arise. 



BOS 



EOS 



The pointer that points to 
the beginning of the current 
segment (see chapter 6) . 

The pointer that points to 
the end of the current 
segment (see chapter 6). 



Address of external save area: 

The address of the save area 
for the calling routine, if 
IBMBPIR was not called from 
the control program. 

Address of translate-and-test table 
for IBMBERR: 

See below, under heading 
"Translate-and-Test Table." 

Address of TCA appendage 

Address of save area for IBMBPGRC and 
IBMBPGRD (see below) 

Open file chain: 



Used when closing files at end 
of job 

Address of IBMBPGRD: 

Stack overflow routine for 
VDAs (see chapter 6) 

Address of the diagnostic file block 
(see below) 
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PL/I and user return code; 



A standard area to keep these 
codes. 

Address of flow staterrent table: 

This is used to address the 
flow statement table which 
holds statement numbers for 
use during execution. 

Address of tab table: 

The address of a table of 
tabulator positions used in 
list-directed output. 

Address of FLOW module: 

The address of the module used 
to implement the compiler FLOW 
option. 

Shared library transfer vector addresses: 

Used when accessing PL/I 
library modules in the link- 
pack-area. 

Address of PRV initialization word: 

Used to access word set in PRV 
when files are closed. 

Address of control task service routines: 

Used to access service 
routines in multitasking. 

Address of storsige-handling routines: 

Entry points to IBMBPGR that 
get non-LIFO storage, free 
non-LIFO storage, and acquire 
a new segment for LIFO storage 
(see chapter 6) . 

Address of IBMBERRB 

Address branched to after a 
software-detected interrupt 
occurs (see chapter 7). 

Environment descriptor: 

Identifies release of 
libraries being used. 

Code for GOTO out of block: 

Whenever a GOTO out of block 
occurs, or could potentially 
occur because of the value of 
a label variable, compiled 
code branches to this code in 
the TCA. 



The function of this code is 
described in chapter 2, under 
the heading "Handling Flow of 
Control. " 

Address of get- control routine: 

Routine used in multitasking 
(see chapter 14) 

Address of free-control routine: 

Routine used in multitasking 
(see chapter 14) 

Address of ENQ SYSPRINT routine: 

Library routine used in stream 
I/O (see chapter 9) 

Address of DEQ SYSPRINT routine: 

Library routine used in stream 
I/O (see chapter 9) 

Address of WAIT module: 

Address of IBMBJWT, the module 
used to execute the WAIT 
statement 

Address of COMPLETION pseudovariable module 

Address of event assign module 

Address of priority routine 

Address of ENQ and DEQ routines: 

Used for enqueuing and 
dequeuing files other than 
SYSPRINT. 



TCA_Imglementation_AEEendage 



The TCA implementation appendage (TIA) is 
addressed from the standard part of the 
TCA. Its contents are as follows: 

Address of the byte beyond the ISA(TISA): 

This holds the address beyond 
the end of the partition and 
is necessary because EOS gets 
altered when non-LIFO dynairic 
storage is allocated. 

Address of old PICA (TAPC) : 

Used to restore SPIE to that 
which existed when the PL/I 
program was called. 

Address of interrupt handler (TERA) : 
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This is the address to which 
the branch is made after a 
program check interrupt (see 
above) has occurred. 



Interrupt mask and flags (TINM) 



Wait information table (WIT) chain header 
(TWTW) : 



Start of the chain indicating 
which events are being waited- 
on in the task. 

Anchor for chain of exclusive blocks (TEXF) 

Used when handling exclusive 
files 

Address of last free area (TLFE) : 

Address of last free area of 
non-LIFO storage on the free 
area chain: used as a starting 
point when searching the 
chain. 

Address dump block (TDUB) : 

Used when a PLIDUMP is being 
executed. 

Address of dummy DSA: 

Used, when abnormally 
terminating the program, to 
restore iBMBPIR's registers. 
This allows IBMBPIR to be 
reached should the DSA chain 
be overwritten. 

Address of get-library-workspace routine: 

This is part of the resident 
library module IBMBPIR and is 
used to get a new allocation 
of library workspace and an 
ONCA. This routine is called 
after interrupts and during 
program initialization (see 
chapter 3). 

Address of extended float simulator (TASM) : 

Used on machines that do not 
have the extended floating- 
point instructions to handle 
extended floating-point data. 

Name of extended float simulator (TSNM) : 

Used to hold the name of the 
extended float simulator, so 
that it can be invoked if 
required . 



Save Area for IBMBPGR 



This area is used as a DSA for IBMBPGR, the 
routine entered when there is not enough 
room for a further DSA in the current 
segment of the LIFO stack. Both DSAs in 
library workspace may be in use when 
IBMBPGR is required, and there may be nc 
caller's save area because a DSA has not 
yet been acquired. Consequently, IBMBPGR 
has a save area reserved in the program 
management area. 



Dummy ONCA 



The dummy ONCA holds default values for the 
condition built-in functions. These will 
be supplied if they are requested either 
when no interrupt has occurred, or when nc 
interrupt with the requested condition 
built-in function value has occurred. 
There is a chain back through all ONCAs to 
the dummy ONCA. (See chapter 7.) 



Translate-and-Test Table 



The translate-and-test table contains code 
used in error handling to identify relevant 
on-cells. (see chapter 7.) 



Dum2_File_Block 



This is space used during the execution of 
PLIDUMP to hold the DCB and other 
information for the dump file. 



Loaded Module or Ordered Delete List 



This is a list of modules that are deleted 
by IBMBPIR during program termination. 
Certain transient modules that are not 
deleted by other methods place their name 
in this list to ensure that they are 
deleted when the program is terminated. 



DlJgtSY.-Tasks .and Eyent.Variables 



These are included in the program 
management areas to allow the use of the 
STATUS and PRIORITY built-in functions in 
non-multitasking programs, and to allow 
multitasking programs to operate if no task 
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or event variables are explicitly declared. 



that are used by certain of the library 
modules. (See chapter 3.) 



Diagnostic File Block 



The diagnostic file block holds information 
used by the error-message modules. This 
includes the address of the SYSPRINT 
transmitter. 



Durarny_DSA 



ON Communications Area (ONCA) 



The ONCA is an area where compiled code or 
library routines can store or read any 
condition built-function values that may be 
required. (See chapter 7.) 



The dummy DSA acts as a save area for the 
registers of the initialization routine 
IBMBPIR, and an end to the chain of DBAs 
when a search through blocks is being made, 
as, for example, when searching for a 
relevant established on-unit (see chapter 
7). The dummy DoA has a bit in its flag 
byte to indicate that it is a dummy. The 
dummy DSA contains a NAB (next available 
byte) pointer enabling the main procedure 
to obtain a DSA in the LIFO stack. 



Library i^orkspace (LWS) 



This consists of two pre-f ormatted DSAs 



Pseudo-Register Vector 



This is used in addressing files and 
controlled variables. (see chapter 2.) 



Multitasking 



The program initialization process for a 
multitasking environment is described in 
chapter 14. 
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Chapter 6: Storage Management 



The OS PL/I optimizing compiler allows the 
user to specify the working storage area he 
wishes to use, by a parameter known as 
ISASIZE. When this parameter is specified, 
the initial storage area (ISA) is set up to 
the size indicated. This is done by 
issuing a GETMAIN macro instruction for the 
required amount of storage. 

If the ISASIZE parameter is not 
specified, or if the ISA size specified is 
greater than the size of the region, 
default action is taken. The default 
action is to issue a variable GETMAIN 
instruction for the largest amount of 
storage possible. Half of this storage is 
allocated to the ISA and the remainder is 
freed for possible future use by the 
program or by the system. 

The allocation of the ISA is handled in 
the program initialization module IBMBPII. 
The procedure for tasking is slightly 
different and is described in the section 
on multitasking at the end of this chapter. 
The initial storage area (ISA) is used for 
various functions during execution. The 
start of the ISA is used as the program 
management area. The program management 
area contains a number of housekeeping 
fields and is set up by the initialization 
routines. (See chapter 5.) The remainder 
of the ISA is used for PL/I dynamic storage 
allocation. 



TYPES OF DYNA^3IC STORAGE REQUIRED 



The requirement for dynamic allocation and 
freeing of storage is inherent in the 
language. Automatic variables are 
allocated and freed on a block-by-block 
basis. Controlled and based variables can 
be allocated and freed by appropriate PL/I 
statements. Storage is also obtained 
dynamically for workspace, and compiler- 
generated temporary values. 

Dynamic storage can be conveniently 
divided into two classes. 

1. That which is allocated and freed on a 
last-in/first-out (LIFO) basis. 

2. That which is not. 

The first class is known as LIFO dynamic 
storage and the second class as non-LIFO 
dynamic storage. 



Certain other storage is also acquired 
dynamically. This is storage for 
transiently loaded library modules and 
input/output buffers. This storage is 
acquired and freed directly under system 
control. Routines wishing to load a 
transient module issue a LINK, LOAD, or 
XCTL macro instruction. When the transient 
module is to be freed the controlling 
library module issues the necessary macro 
instruction. 



Contents of LIFO (Last-In/First- Out ) 
Storage 



Two kinds of storage area are allocated in 
LIFO storage. They are dynamic storage 
areas(DSAs) and variable data areas (VDAs) . 
A DSA is allocated for every procedure or 
block and contains: 

• The System/360 standard save area. 

• Certain standard housekeeping fields. 

• All automatic variables and compiler- 
generated temporaries whose length is 
known during compilation. 

A diagram of the standard section of a DSA 
is shown in appendix A. 

VDAs are acquired for all other 
allocations of LIFO dynamic storage. These 
include: 

• Storage for automatic variables and 
compiler-generated temporaries whose 
length is not known until execution. (X 
CHAR(N), for example.) 

• Workspace for certain library modules. 

• Allocations of library workspace (LWS) 
after the occurrence of an interrupt. 



Contents pf Non-LIFO Storage 

Non-LIFO storage is used for the following: 

• Controlled variables. 

• Those based variables that are allocated 
by the ALLOCATE statement, (provided 
that they are not allocated in an 
automatic or static AREA) . 
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Dynamic Storage Allocation 



The principle used in dynamic storage 
allocation is to allocate LIFO storage from 
the low-address end of ISA, starting at the 
first 8-byte boundary beyond the program 
management area, and to allocate non-LIFO 
storage from the high-address end of the 
ISA. Between the areas of LIFO and non- 
LIFO storage is an unused section known in 
this publication as the major free area. 
(See figure 6.1.) 

The last element in the LIFO stack is 
always the first to be freed and 
consequently can always be amalgamated with 
the major free area. This is not always 
the case with non-LIFO storage. When an 
item not contiguous with the major free 
area in the non-LIFO stack is freed, it is 
placed on a free-area chain whose head is 
anchored in the TCA. Attempts are always 
made to use areas on this chain when 
further allocations of non-LIFO storage are 
made. 

Allocations of LIFO storage are made by 
testing to see if there is enough space in 
the major free area. If there is not 
enough space, an attempt is made to use an 
area on the free-area chain. When an area 
on the free-area chain is used, it is known 
as a new segment of the LIFO stack. 

If there is no space either in the major 
free area or on the free area chain, then a 
GETMAIN macro instruction is issued to 
obtain new storage. For LIFO storage this 
will be set up as a new segment of the LIFO 
stack and the necessary housekeeping fields 
will be placed at its head. 



Fields_ysed in Storage Handling 



start of the current storage segment. BOS 
is held at offset 8 from the head of the 
TCA, and is addressed from register 12. 

The end-of -segment pointer_J[EOS) is 
initially set during program initialization 
to point to the end of the ISA. However, 
it is updated, when non-LIFO storage is 
allocated, to point to the end of the major 
free area. EOS is held at offset X*C' (12) 
in the TCA, and is addressed from register 
12. 

The next-ayailable-byte pointer (NAB) is 
held in every DSA and points to the first 
8-byte boundary contiguous with unused 
storage. This address is the start of the 
major free area. The current NAB is held 
in the most recent DSA and addressed from 
offset X'4C'(76) from register 13. As 
register 13 is altered every time a DSA is 
acquired, the value in a NAB pointer need 
only be altered when a VDA is freed or 
acquired. Previous NABs are automatically 
restored when register 13 is pointed to a 
previous DSA. 

The pointer _to the byte beyond the _IS A 
(TISA) is used to keep track of the end of 
the ISA. 

The first byte of BOS, EOS, and NAB 
contain segment numbers ("FF" for the ISA). 
The use of these numbers is explained under 
"Acquiring a New Segment." 

The free area chain pointer TLFE. The 
free-area chain includes those elements of 
non-LIFO dynamic storage that have been 
freed but that could not be amalgamated 
with the major free area. The start of the 
chain is held at offset 8 in the TCA 
appendage in a field called TLFE. TLFE 
points to the element with the highest 
address. 



To keep track of the storage allocated and 
freed, a number of pointers are used. 
These are: 

• The beginning-of-segment pointer (BOS) . 

• The end-of-segment pointer (EOS). 

• The next-available-byte pointer (NAB) . 

• The free-area chain pointer TFLE. 

• A pointer to the byte beyond the end of 
the ISA (TISA). 

The beginning-of-segment pointer (BOS) is 
initially set during program initialization 
to point to the start of the ISA. It is 
not altered unless a new segment of storage 
is acquired. BOS always points to the 



ALLOCATING AND FREEING LIFO STORAGE 



Allocating and freeing LIFO storage is 
handled by compiled code or by the 
particular library module that requires the 
space. The allocation is done in the 
manner used by the prologue code shown in 
chapter 2. Freeing is done in the manner 
used by the epilogue code, which is also 
shown in chapter 2. Before allocating the 
storage, a test is made to see if there is 
enough space in the major free area for the 
new allocation. For reasons explained later 
under the heading "Acquiring a New 
Segment," this test is carried out by 
logical arithmetic. If there is not enough 
space, entry to one of the segment-handling 
entry points of the transient library 
module IBMBPGR is made. The entry point 
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13, the previous values are 
automatically restored. 



Figure 6.2. principles involved in allocating and freeing LIFO storage 
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Figure 6.3. Principles involved in allocating and freeing non-LIFO storage 



used depends on whether a VDA or a DSA is 
being acquired. The allocation of LIFO 
storage involves accessing the current 
value of NAB. This gives the address of 
the start of storage to be used. A new NAB 
value is calculated, addressing the byte 
beyond the end of the new allocation. 
Register 13 is pointed at the old NAB value 
and the new NAB value placed at offset 
X*4C' from register 13. Freeing the 
storage is done by restoring register 13 to 
the previous value. Figure 6.2 illustrates 
the principles involved. Before allocating 
the storage, a test is made to see if there 
is enough space for the allocation. When 
there is insufficient space for a LIFO 
storage allocation, a new segment is 
acquired. (See below.) 



ALLOCATING AND FREEING NON-LIFO STORAGE 



Any section of non-LIFO storage can be 
freed at any time; therefore a simple 
stacking mechanism cannot be used, because 
it would waste storage by leaving freed 
storage within the stack. A different 
method is therefore used. When storage 
that is contiguous with the major free area 
is freed, it is amalgamated with the major 
free area by altering the end-of-segment 
(EOS) pointer, which indicates the end of 
this area. When storage that is not 
contiguous with the major free area is 
freed, it is placed on the free-area chain, 
which is anchored to a field in the TCA 
appendage, whenever an allocation is made, 
an attempt is made to place the allocation 
in an area that is already on the chain, 
rather than use a further section of the 
major free area. Allocations of non-LIFO 
dynamic storage are always handled by the 
library module IBMBPGR, whose address is 
held in the TCA. Figure 6.3 illustrates 
the principles involved. Whenever an 
allocation within the major free area is 
made, the end-of-segment (EOS) pointer, in 
the TCA, is updated to point to the end of 
the major free area. 

If there is not sufficient space in 
either the major free area or on the free 
area chain, a GETMAIN macro instruction is 
issued for the required amount of storage. 
Non-LIFO storage acquired by a GETMAIN is 
freed by a FREEMAIN macro instruction. 



and the EOS pointer. If there is not 
enough space then an attempt is made to use 
the largest space on the free-area chain as 
a new segment for the DSA or VDA. 

Pointers BOS and EOS in the TCA are set 
to point to the beginning and end, 
respectively, of the new segment. The DSA 
or VDA is allocated storage in the low- 
address end of the segment, and the NAB 
pointer is set to point to the first free 
byte after the DSA or VDA. The former 
values of BOS and EOS are stored at the 
start of the new segment. 

A segment number is given to each 
segment, starting at hexadecimal "FF" and 
decreasing by 1 for each new segment. The 
number for the ISA is "FF", the second 
segment "FE", and so on. This number is 
held as the first byte of the NAB, BOS, and 
EOS pointers. The result of this device is 
that, when logical arithmetic is used, all 
addresses in later segments are apparently 
less than those in the earlier segments, 
regardless of their actual position. This 
simplifies segment handling. For instance, 
when a DSA in the second segment is freed, 
NAB is simply restored to its previous 
value which may well be in the first 
segment. NAB will then hold value 

"FF ", and EOS the value "FE ". 

When a further DSA is required, EOS will be 
less than the sum of NAB and the DSA 
length, as EOS is already less than NAB. 
Consequently it will appear that there is 
insufficient space for the DSA in the first 
segment, regardless of whether or not this 
is the case. The library module IBMBPGR is 
thus called to restore BOS and EOS, add the 
emptied segment to the free-area chain, 
and, if possible, place the new DSA after 
NAB in the first segment. The process is 
illustrated in figure 6.5. 



IBMBPGR - STORAGE MANAGEMENT ROUTINE 



The allocation and freeing of LIFO storage 
within a given segment is handled by 
compiled code or by the library module 
requiring the storage. All other dynamic 
storage allocation is carried out by the 
resident library routine IBMBPGR; this 
module has four entry points: 

IBMBPGRA Allocate non-LIFO storage. 



ACQUIRING A NEW SEGMENT OF LIFO STORAGE 



Every time a new procedure or block is 
entered, or a VDA is acquired, a test is 
made to see whether there is enough space, 
for the DSA or VDA, between the NAB pointer 



IBMBPGRB Free non-LIFO storage. 

IBMBPGRC Obtain and free additional 

storage segments (for DSAs) . 

IBMBPGRD Obtaining and freeing additional 
storage segments (for VDAs). 
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These four entry points are described 
below. In all cases storage is allocated 
in multiples of 8 bytes. 



Allocating Non-LIFO Storaqe_iIBMBPGRA) 



When entered by entry point IBMBPGRA, the 
module first searches the free-area chain, 
(if one exists) and allocates the storage 
in the smallest possible area on the chain. 
If there is no chain, or no area on the 
chain that is large enough, IBMBPGR 
attempts to allocate the storage in the 
area immediately preceding the EOS pointer, 
If there is not enough space between the 
EOS pointer and the current NAB pointer, a 
GETMAIN macro is issued for the required 
storage. If the GETMAIN cannot be 
satisfied, the system ends the job with an 
ABEND-code 80A. This ABEND is intercepted 
by the ABEND analyzer IBMBPES. IBMBPES 
puts out a message indicating which 
statement was being executed and when the 
demand for storage was made. It then 
returns to the system to complete the 
ABEND. 

Provided that storage can be allocated, 
control is passed back, with register 1 
pointing to the address of the storage 
allocated. 



being freed can be amalgamated with areas 
already on the chain. This is done if 
possible. The module then checks to see 
whether the storage being freed is adjacent 
to the major free area. If so, EOS is 
altered to point to the end of the area 
being freed or to the end of the 
amalgamated area, if this adjoins the major 
free area. If the element cannot be 
amalgamated with any other, the area is 
added to the free-area chain, which is 
arranged in descending order of addresses. 
The format of a free area chain element is 
shown in figure 6.4. 



0, , 

Length of element in bytes 

Pointer to area with lower address, 
zero if last element 



Unused storage 



L 



. J 



Figure 6.4. Format of element on free 
area chain 



Non-LIFO Storage .(IBMBPGRB) 



segment Handling (IBMBPGRC and 
IBMBPGRD) 



When freeing non-LIFO storage or segments 
of LIFO storage IBMBPGR first tests to 
discover whether the element being freed is 
within the ISA. This is done by seeing if 
the address is between the value held in 
register 12, the address of the TCA, and 
the value held in the TISA field of the ISA 
which points to the end of the ISA. If the 
element is outside the ISA it must have 
been acquired with a GETMAIN macro 
instruction. It is therefore freed with a 
FREEMAIN macro instruction. 

If the element to be freed is within the 
ISA,, the module scans the free-area chain 
(if one exists) to see whether the storage 



When compiled code discovers that the 
address contained in the pointer NAB plus 
the length of the new DSA or VDA to be 
allocated is greater than the value of the 
pointer EOS, IBMBPGR is called either at 
entry point C or entry point D depending on 
whether the storage is required for a DSA 
or for a VDA. Entry point C is used if a 
DSA is required, entry point D, if a VDA is 
required. The difference is the method 
used to store the caller's registers. 
IBMBPGRC stores the caller's registers in a 
special save area in the TCA, because no 
DSA has yet been acquired; IBMBPGRD stores 
the registers in the caller's DSA, in the 
usual manner. 
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Initial situation 

1. Free-area chain exists. 
BOS, NAB, and EOS have 
X'FF' in first byte, i.e., 
segment number 1. 



Acquiring new segment 

1. Compiles code or library 
routine finds major free 
area too small. Calls 
IBMBPGR. 

2. IBMBPGR finds an area on 
free-area chain large 
enough for allocation. 

3. Stores old BOS and EOS. 
Sets new BOS and EOS, and 
returns to caller. 

4. Caller gets new DSA. 
BOS, EOS, and NAB have 
X'FE' in first byte, i.e., 
segment number 2. 



Freeing DSA in segment 

1 . Register 1 3 is restored in 
the normal way. BOS and 
EOS are not restored. The 
segment will not be freed 
until there is a further 
demand for storage, that 
can be accommodated 

in the previous segment. 

2. NAB now has X'FF' in first 
byte, BOS and EOS still 
have X'FE'. 



Freeing segment 

1 . When storage is ag»s required, 
NAB + storage required is 
compared with EOS using 
logical arithmetic. 

2. NAB -^ storage is found to be 
greater (because of different 
segment numbers), so IBMBPGR 
is called. 

3. I BIMBPGR finds segment 
numbers are different. Tests to 
see if new storage will fit in old 
segment. If not, allocates in 
current segment. 

4. Storage will fit, so restores old 
BOS and EOS, places segment 
on free-area chain, and returns 
to caller. 

5. Caller allocates storage starting 
at current NAB. 
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Figure 6.5. Principles involved in allocating and freeing segments of PL/I dynamic storage 



The entry points are called in two 
circumsta nces : 

1. There is insufficient room in the 
current segment for allocation of the 
DSA or VDA and, consequently, a new 
segment is required. 

2. A segment other than the first one has 
been allocated, but is no longer in 
use. 

IBMBPGRC and IBMBPGRD check to see which 
of the above two situations caused the 
call. This is done by determining whether 
the number in the first byte of NAB is 
greater than the number in the first byte 
of EOS. 

In case 1 above, the segment numbers are 
the same, and a new segment must be 
allocated. A new segment is allocated by 
searching the free-area chain for the 
largest available area and using this as a 
new segment. If there is no area large 
enough to hold the new DSA, a GETMAIN macro 
instruction is issued and the new segment 
set up in the area acquired. 

When a new segment is allocated, the old 
values of BOS and EOS are placed in control 
words at the head of the new segment. New 
values for BOS and EOS pointing to the 
beginning and end of the new segment, with 
first byte numbers decremented by one, are 
placed in the TCA. The address of the new 
NAB is passed in register zero; the address 
for the start of the new DSA or VDA is 
passed in register 1. The format of a 
secondary segment is shown in figure 6.6. 
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Previous BOS value 
Previous EOS value 



T < — current 
BOS 



DSA or VDA 



Major Free Area 



Figure 6.6. 



j<. 

Format of second and 
subsequent segments of the 
LIFO stack 



Current 
•EOS 



control words at the head of each segment 
and freeing the storage in the way 
described for IBMBPGRB above. 

When only one empty segment remains, a 
test is made to see whether the new DSA 
will fit into the segment that contains the 
present NAB pointer (the segment before the 
empty segment) . This test is made by 
comparing the current NAB pointer with the 
old EOS pointer held in the control words 
of the empty segment. If there is 
sufficient room, the empty segment is freed 
as described under IBMBPGRB above. Return 
is then made to the caller, with a new 
value for EOS and BOS, and the DSA is 
allocated immediately after the old NAB. 

If there is not enough room in the 
segment containing NAB, then a test is made 
to see if the empty segment is large enough 
to hold the new DSA. This is done by 
comparing the difference between the 
current BOS and EOS with the length of the 
element. If there is enough room, the DSA 
is allocated in the empty segment. The 
address of the start of the storage is 
passed to compiled code in general register 
1, and the address of the new NAB passed in 
general register 0. 

If there is not enough room in the empty 
segment, then the segment is freed. There 
are now no empty segments, and the 
situation is treated as if there had been 
no empty segments in the first place. 

?i2fe§* I^ is possible that after freeing a 
number of empty segments, an area on the 
free-area chain can immediately follow EOS. 
However, the possibility is remote, and no 
check is made to see whether this is the 
case. 



Storage Reports 



When the PL/I programmer requests a storage 
report, he is given, after the completion 
of his program, a report showing the 
following: 

1. The ISA size specified (if a size was 
specified) . 

2. The ISA size used. 



In case 2 above, the number in the first 
byte of NAB is greater than the number in 
the first byte of EOS. If the difference is 
greater than one, more than one extra 
segment has been allocated for DSAs or VDAs 
which are no longer current. In this case, 
segments are freed until only one empty 
segment remains. This is done by setting 
BOS and EOS to the values held in the 



3. The amount of PL/I storage required by 
the program. (This is a suggested 
optimum ISA size.) 

U. The maximum amount of storage obtained 
outside the ISA at any one time. 

5. The number of GETMAIN macro 
instructions issued. 
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6. The number of FREEMAIN macro 
instructions issued. 

7. The number of requests to acquire non- 
LIFO storage. 

8. The number of requests to free non- 
LIFO storage. 

The report is generated by the storage 
report routine, IBMBPGD. This module is 
loaded during program initialization, 
instead of the normal storage management 
module IBMBPGR. IBMBPGD has the same entry 
points and carries out the same functions 
as IBMBPGR. However, it also maintains a 
record of certain storage statistics. To 
ensure that IBMBPGD handles all storage 
allocation both inside and outside the ISA, 
the EOS field in the TCA is set with a 
dummy value so that the storage routine 
will be called whenever LIFO storage is 
required, as well as for non-LIFO storage 
and stack overflow requests. 

The storage report is issued during 
program termination. The termination 
routine,, IBMBPIT, calls the report writing 
module, IBMBPMR. The report is transmitted 
to the dump file. 



Action during _ Initialization 



During program initialization, if REPORT 
has been included in the parameters passed 
to IBMBPIR, the report storage management 
routine IBMBPGD is loaded, and its entry 
point addresses placed in the TCA. The 
value in the end-of-segment pointer, EOS, 
is then set to zero. Space for a report 
table is acquired, and the true value of 
the end of segment placed in a field in the 
report table. 



j^gfeioS...^^?ipg.-. Execution 



During execution, IBMBPGD is called every 
time there is a request for PL/I dynamic 
storage. It is called for non-LIFO storage 
in the normal way, and, when LIFO storage 
is required, it is called because the zero 
value in EOS results in the value of 
NAB+DSA or VDA being greater than EOS. 
Consequently, the stack overflow routine 
(IBMBPGD, entry point C or D) is called. 
When a call is made to entry points C or D, 
IBMBPGD makes a test against the true value 
of the end of segment held in the report 
table, and, if there is sufficient room, 
the storage is acquired in the current 
segment of the LIFO stack. If there is not 
sufficient room, IBMBPGD takes the same 



action as IBMBPGRA (describejd earlier in 
this chapter) . 

All other storage acquisition by IBMBPGD 
is handled in exactly the same way as for 
the corresponding entry point of IBMBPGR. 
However, IBMBPGD keeps a running total of 
the following in the storage report table. 

1. The highest value obtained by 
subtracting the current length of the 
major free area from the current 
amount of PL/I storage acquired 
outside the ISA. 

2. The largest amount of PL/I storage 
obtained outside the ISA at any one 
time. 

3 . The number of GETMAIN macro 
instructions issued. 

U. The number of FREEMAIN macro 
instructions issued. 

5. The number of requests to acquire non- 
LIFO storage. 

6 . The number of requests to free non- 
LIFO storage. 

The values are altered if necessary every 
time IBMBPGD is entered. The value of (1) 
and (2) above is calculated on every call, 
and the highest number retained in the 
report table. The format of the storage 
report table is given in appendix A. 



Action on Termination 



On termination, the termination routine, 
IBMBPIT, calls the storage report writing 
module, IBMBPMR, which transmits the 
storage report onto the dump file. 

The amount of PL/I storage required is 
calculated by adding the figure described 
in (1) above to the ISA size used. The 
figure will be positive if any storage 
outside the ISA was acquired; it will be 
negative or zero if no storage was acquired 
outside the ISA. 

Two things should be noted about the 
results produced by a storage report. 

1. If storage was acquired outside the 

ISA, the figure given for storage used 
cannot be taken as final. A further 
request for a report when the program 
is run in the ISA size suggested may 
result in a smaller figure being 
generated. This smaller size should 
be used. This discrepancy is caused 
by the differences in acquiring 
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storage inside and outside the ISA. 
To obtain a correct figure using only 
one run, the program should be run in 
a large ISA that can be expected to 
hold all PL/I storage. 

2. The report can only refer to the 

particular run of the program on which 
the report was given. Runs with 
different data or parameters may have 
different storage requirements. 

The modules IBMBPGD, IBMBPMR, and the 
initialization and termination modules are 
fully described in PL/I transient library 
program logic manual. 



Storaqe_ReEorts_for _Multitaskin 
Programs 



Storage reports for multitasking programs 
are generated in the same way as those for 
non-multitasking programs. A special 
storage management module is loaded at 
execution time, and this retains statistics 
of the amount of storage used. To ensure 
this module handles all requests for 
storage, the value in EOS is set to zero, 
and the true EOS value is retained in the 
report table. The report is issued during 
program termination by the module IBMBPMR. 

For a multitasking storage report the 
following information is given: 

For the major task: 

The same as for a non-multitasking 
program (see above). 

For subtasks, a combined report for all 
subtasks showing: 

The maximum ISA size used by any subtask 

The minimum ISA size used by any subtask 

The maximum PL/I storage required by any 
subtask 

The minimum PL/I storage required by any 
subtask 

The maximum amount of storage acquired 
outside the ISA by any subtask 

The minimum amount of storage acquired 
outside the ISA by any subtask 

The total number of GETMAIN and FREEMAIN 
macro instructions issued by all 
subtasks 

The total number of requests to free and 
acquire non-LIFO storage issued by all 



tasks 

To enable these figures to be produced, 
a multitasking version of the storage 
report module is used. This module, 
IBMTPGD, has two more entry points than its 
non-multitasking counterpart. These are: 

IBMTPGDE - called when a task is 
initialized. 

IBMTPGDF - called when a task is 
terminated. 

IBMTPGDE is called when a task is 
initialized. It acquires storage for the 
report table for the task, and retains a 
record of the number of active PL/I tasks, 
increasing the maximum number if necessary. 

IBMBPGDF is called when a task is 
terminated. If the terminated task is a 
subtask, IBMBPGDF completes the relevant 
field in the subtask storage report table, 
from information in the report table of the 
terminating task. 

During initialization, space is required 
by the control task for a combined subtask 
report table which will hold the 
information from which the merged subtask 
report will be generated. During the 
initialization of each task, space for a 
report table for that task is obtained. 
The report table for the major task is 
flagged. 

Throughout the execution of each task, a 
separate report table is maintained. At 
the end of each subtask, the information in 
the terminating task is merged into the 
combined subtask table, held in the storage 
associated with the control task. 

When the jobstep is terminated, IBMBPMR 
produces the information from the merged 
subtask report table and the report table 
of the major task. (IBMBPMR is used to 
output the report for both tasking and non- 
tasking programs.) 



Storage Management in Programmer-allocated 
Areas 



By using area variables, the programmer can 
obtain a continuous area of storage for 
based variables. The allocation of storage 
for area variables is handled in the same 
way as that for other types of variable, 
and depends on the variable's storage 
class. The allocation and freeing of 
storage within an area is handled by the 
library module IBMBPAM. 

IBMBPAM keeps a check on the amount of 
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storage allocated. If there is not enough 
space for an allocation, or if the target 
area is too small to hold the source area 
assignment statement, the AREA condition is 
raised. 

The method employed is that storage is 
allocated from the low-address end of the 
area, and an offset is kept to the end of 
the item with the highest address in the 
area. This offset is known as OEE (offset 
to end of extent). When storage is freed, 
either the OEE is altered or the storage is 
placed on a free-storage chain, with the 
largest segment at the start of the chain. 

Before a space is freed, a check is made 
to see whether it is contiguous with a 
space or spaces that are already on the 
free storage chain. If it is, the 
contiguous spaces are amalgamated. A check 
is then made to see whether the amalgamated 
space is contiguous with the OEE. If the 
space is contiguous with the OEE, the OEE 
is pointed to the start of the space, and 
the space removed from the free storage 
chain. If the amalgamated space is not 
contiguous with the OEE, the free area 
chain is rearranged so that it is in the 
correct order. 

If the space to be freed is not 
contiguous with another space on the free 
storage chain, a check is made to see if it 
is contiguous with the OEE. If it is, the 
OEE is updated. 

If the space to be freed is contiguous 
neither with the OEE nor with another space 
on the free storage chain, the space is 
placed in its correct position in the 
storage chain. 

When a free chain exists, IBMBPAM always 
attempts to allocate storage by using a 
space on the chain. The low-address end of 
the smallest possible space on the chain is 
used, and the chain is then rearranged to 
maintain the correct order of decreasing 
size. 



the pattern described above, except that 
certain storage requests are made for 
storage that will be available to all 
tasks. This storage has to be obtained in 
subpool 0. To indicate such a requirement, 
IBMTPGR is called with a negative value. A 
GETMAIN for the specified amount is then 
issued to subpool 0, the negative value 
indicating what the storage must be in 
subpool 0. 

The method used to acquire the ISA is 
slightly different for tasking. This is 
described below. 



Multitasking Considerations 



storage handling within each task follows 



Acquiring the ISA when Jjultitasking 



The size of the ISA required for the major 
task and every minor task can be requested 
in the ISASIZE parameter of the EXEC card. 
If the size in the parameter is smaller 
than that needed for the program management 
area, only the exact size required for the 
program management area is acquired and all 
further allocations of dynamic storage are 
made by issuing GETMAIN macro instructions. 
These allocations are made in exactly the 
same way as they are when non-tasking 
programs cannot acquire space within the 
ISA, see above under "IBMBPGR - Program 
Management Routine". 

The default action, taken if no ISA size 
is specified, is to acquire storage for all 
ISAs in multiples of UK bytes. If the 
program management area can be contained in 
UK bytes (which will normally be the case) 
only UK bytes are acquired and this is set 
up as the ISA. If the program management 
area contains more than UK bytes, (an 
exceptionally large PRV might cause this) a 
further UK bytes are acquired. This 
process continues until enough space is 
acquired for the program management area. 

UK bytes of storage will normally be 
enough to hold the program management area 
and the DSA for the main procedure. 
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DETECTING CONDITIONS 



SYSTEM 



B 



COMPILED CODE OR LIBRARY ROUTINES 



Use system facilities if 
possible. SPIE macro, 
issued during initialization, 
passes control to error 
handling module when 
interrupts occur 



Execute checking code 
for all enabled conditions 
not detected by system. 
Call error handler 
when condition detected. 



INDICATING ACTION REQUIRED WHEN CONDITION OCCURS 



COMPILED CODE 



Set up flags indicating which 
conditions are enabled. 
Set up control blocks indicating 
which ON statements have been 
executed and, consequently, 
which on-units are established 
and the addresses of such 
on-units. 



CONTROLLING ACTION AFTER CONDITION HAS OCCURRED 



ERROR HANDLING MODULE - IBMBERRi 



From information set up in control blocks and flags by compiled code, determine which of the 
following actions to take when an interrupt has occurred 



If condition disabled 

Ignore interrupt and 
return. 



If on-unit established 

Take action specified 
in on-unit. If no 
GOTO out of on-unit 
take action specified 
for normal return 



X 



If no on-unit established 

Take standard system 
action as defined in 
the language 



Figure 7.1. The principles of error handling 
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Chapter 7: Error and Condition Handling 



This chapter deals with the method used to 
implement execution_tiine error handling. 
All errors detected at execution time are 
associated with PL/I conditions and can be 
handled either by on-units written by the 
programmer or by standard system action, as 
defined in the PL/I language. 

The chapter starts with a brief 
discussion of the terms and concepts used 
in error handling. A discussion of the 
error handling facilities offered by the 
operating system and those specified in the 
PL/I language follows. The implementation 
problems these facilities raise and the 
method used to solve them are then 
described. A separate section is devoted 
to the CHECK condition because this raises 
special problems. The chapter is completed 
by a brief discussion of the error message 
modules, the modules used to implement the 
PLIDUMP facility, and the handling of the 
compiler FLOW option. 

Error detection during compilation is 
not covered in this chapter. Nor is any 
advice given on how to use PL/I error 
handling facilities. Advice on debugging 
with dumps is given in chapter 12. 

Note: If the NOSPIE or NOSTAE options are 
specified in the parameters for the 
procedure, much of what is said in this 
chapter does not apply. The PL/I SPIE or 
STAE macros will not be issued and system 
detected interrupts and ABENDS will not be 
handled in the PL/I defined manner. 



Terminology 



Throughout this chapter a number of special 
terras are used, some of them are terms used 
in the PL/I language, others are terms that 
are used to describe certain implementation 
features and concepts. The terms are listed 
below. 

Established; This term is used to describe 
on-units and, sometimes, ON statements. 
The on-unit or statement is said to be 
"established", if the action specified in 
the on-unit or ON-statement will be taken 
should the specified condition arise. Thus 
an on-unit becomes established when the ON 
statement is executed and ceases to be 
established when an ON or REVERT statement 
referring to the same condition is 
executed, or when the associated block is 
terminated. 



Enabled; This term is used to describe 
certain PL/I conditions (SIZE, CONVERSION, 
etc.). A condition is enabled when the 
occurrence of the condition will result in 
the execution of an on-unit or standard 
action. A condition is disabled when the 
occurrence of the condition will, 
apparently, be ignored. 

Qualified conditions are those conditions, 
such as ENDPAGE, that need to be qualified 
by a file or other name. Unqualified 
conditions are those that do not need 
qualification. Figure 7.3 shows which 
conditions are qualified and which are 
unqualified. 

Program_Check„and_^Software_Interrupts; 
Certain PL/I conditions are detected 
automatically by the computing system. 
Others have to be detected by special 
checking code either in library modules or 
in the compiled program. Interrupts 
detected by the system are referred to as 
pr ogram_check . Interrupts detected by 
special checking code are referred to as 
^2£t^£§Z^§tected or software interrupts. 
A list of program check interrupts and 
their associated PL/I conditions is given 
in figure 7.2. 

These terms program check and software 
interrupts are used, for convenience in this 
publication and are not accepted terms in 
the PL/I language. Figure 7.3 shows which 
interrupts are system detected and which 
are software detected. 

Static and_Dynamic_De3cendency; Static and 
dynamic descendency are terms used to 
define the scope of PL/I features. On- 
units are dynamicallY descendent. That is, 
they are inherited from the calling 
procedure in all circumstances. Condition 
enablement is statically descendent . That 
is, it is inherited from the containing 
block in the source program. Static 
descendency can be determined during 
compilation. Dynamic descendency cannot be 
known until execution. See figure 7.4. 

^ormal_Return; Normal return is return 
from a called block by means of reaching 
the END or RETURN statement rather than 
because of a GOTO out of the block. In an 
error- handling context, normal return is 
taken to mean normal return from the on- 
unit. The action taken after normal return 
from an on-unit is specified in the PL/I 
language. For most conditions, it is to 
return to the point of interrupt. 
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standard Systetn_Act. jLon ; Standard system 
action is the name given to the default 
PL/I-defined action taken when a condition 
occurs and there is no established on-unit 
for that condition. 



[Machine interrupt 



I PL/I condition 



Operation 




Privileged operation 




Execute 




Protection 


ERROR 


Addressing 


(after issuing 


Specification 
Data 


a message) 


Fixed-point overflow 


FIXEDOVERFLOW/SIZE 


Fixed-point divide 


ZERODIVIDE/SIZE 


Decimal overflow 


FIXEDOVERFLOW/SIZE 


Exponent overflow 


OVERFLOW 


Exponent underflow 


UNDERFLOW 


Floating-point divide 


ZERODIVIDE 



L J 



Figure 7.2, 



Machine interrupts 
associated with PL/I 
conditions 



f 

Background to Error Handling 



System Facilities 



The operating system offers certain 
error-handling facilities. These can be 
summarized as follows: 

Various situations can cause an machine 
interrupt which results in entry to the 
supervisor. It is possible for the 
programmer to define the action that will 
be taken after any of these interrupts by 
means of a routine specified in a SPIE 
macro instruction. Alternatively, the 
programmer can accept the default action of 
the system. It is also possible for the 
programmer to prevent the occurrence of 
certain interrupts by masking out fields in 
the PSW. 



PL/I FACILITIES 



The PL/I language offers similar but 
greatly extended facilities. The number of 
situations causing interrupts is 
considerably larger and some, such as 
ENDFILE, can be used to control normal 
program flow rather than to handle errors. 
The use of on-units allows the programmer 
to obtain control after any interrupt. 



Alternatively he can accept standard system 
action. The programmer also has the choice 
of whether certain of the conditions will 
cause interrupts. This is done by enabling 
or disabling the conditions. If the 
condition is disabled neither an unit nor 
standard system action will be taken if the 
condition occurs. 



A number of PL/I conditions correspond 
directly to the interrupts that are 
detected by the operating system (see 
figure 7.2). Other conditions however 
belong only to PL/I. 

The majority of PL/I conditions are 
caused by errors in program logic or the 
data supplied. Some, however, are not 
connected with errors. These are conditions 
such as ENDFILE, which occur at 
unpredictable times and consequently cannct 
easily be anticipated by code in the source 
program. 

Conditions that are most probably caused 
by programming errors are known as error 
conditions. Figure 7.3 shows which 
conditions are error conditions. The 
standard system action for these conditions 
is to put out a message and raise the ERROR 
condition. 

The ERROR condition is also raised by 
any programming error that is not directly 
covered by a PL/I condition. A data 
interrupt, for example, raises the ERROR 
condition, and certain software detected 
conditions, such as taking the square root 
of a real negative number, also raise the 
ERROR condition. 

The ERROR condition consequently gives 
the programmer blanket coverage of all 
program errors. The ERROR condition differs 
from other conditions in that a diagnostic 
message is always generated regardless of 
whether an ERROR on-unit exists. If an on- 
unit exists, the message is generated 
before on-unit action is taken. 

A further facility offered by PL/I is 
the availability of condition built-in 
functions and pseudo- variables. These 
allow the programmer to inspect various 
fields associated with the interrupt and, 
in certain cases, to alter the contents of 
these fields. 

The situation in PL/I is complicated by 
the question of the scope of on-units and 
condition enablement. Condition enablement 
is statically descendent and can be decided 
during compilation. On-units, however, are 
dynamically descendent and the 
establishment or otherwise of on-units can 
only be decided during execution. (See 
"Terminology" above.) 
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j Name of 
1 condition 


Qual- 
ified 


Description 


Recognized by 


Default 


Program 

-mer 

Control 


ERROR ♦♦ 
Condition 


1 Computational 
















1 CONVERSION 


no 


Attempt to 
convert invalid 
character string 


Code in 
library 


relevant 
modules 


enabled 


yes 


yes 


1 FIXEDOVERFLOW 


no 


Overflow of a 
fixed point 
value 


System 




enabled 


yes 


yes 


1 SIZE 


no 


Attempt to 
assign too large 
a value 


Compiler-generated 
checking code, or 
hardware 


disabled 


yes 


yes 


1 OVERFLOW 


no 


Overflow of a 

floating-point 

value 


System 




enabled 


yes 


yes 


1 UNDERFLOW 


no 


Exponent becomes 
smaller than 
permitted 
minimum 


System 




enabled 


yes 


no 


1, ZERODIVIDE 


no 


Attempt to 
divide by zero 


System 




enabled 


yes 


yes 


1 ISEUt/OutEUt 
















1 ENDFILE 


yes 


End of file 
reached 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


1 ENDPAGE 


yes 


End of a page On 
a print file 
reached 


Code in 
library 


relevant 
modules 


enabled 


no 


no 


1 TRANSMIT 


yes 


Transmission 
error on a file 


Code in 
modules 


library 


enabled 


no 


yes 


] UNDEFINEDFILE 


yes 


Error in opening 
file 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


1 KEY 


yes 


Invalid key 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 


1 NA^3E 


yes 


Unrecognizable 

data-directed 

input 


Code in 
library 


relevant 
modules 


enabled 


no 


no 


1 RECORD 


yes 


Incorrect size 
record 


Code in 
library 


relevant 
modules 


enabled 


no 


yes 



L ^ J 



Figure 7.3. (Part 1 of 2) . PL/I conditions 
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Name of 
Condition 


Qual- 
ified 


Description 


Recogniz 


ed by 


Default 


Program 

-mer 

control 


ERROR** 
condition 


Program Checkout 
















SUBSCRIPT RANGE 


no 


Array subscript 
outside declared 
bounds 


Compiler- 
checking 


-generated 
code 


disabled 


yes 


yes 


STRINGS IZE 


no 


Attempt to 
assign a string 
of too great 
length 


Code in relevant 
library modules 


disabled 


yes 


no 


STRINGRANGE 


no 


Attempt to 
access beyond 
limits of string 


Code in ] 
library i 


relevant* 
nodules 


disabled 


yes 


no 


CHECK 

(variable or 
label) 


yes/ 

no 


Value assigned 
to identifier or 
control passed 
through label 


Compiler- 
checking 
library i 


-generated 
code, or 
nodule 


disabled 


yes 


no 


List Processing 
















AREA 


no 


Attempt to 
allocate beyond 
end of area 


Relevant 
modules 


library 


enabled 


no 


yes 


System Action 
















ERROR 


no 


Any error 
condition 
including those 
not covered by 
other 
conditions** 


Relevant 
modules, 
compiled 
system 


library 
or 
code, or 


enabled 


no 




FINISH 


no 


Program about to 
be terminated 


Relevant 
modules 


library 


enabled 


no 


- 


Programmer Named 
















CONDITION 
(name) 


no 


Programmer 

defined 

condition 


Signal 
statement 


enabled 

(when 

coded) 


no 


— > 



J 

* When STRINGRANGE is enabled, library modules are always called to handle substring 
operations. These modules have the necessary code for checking for the STRINGRANGE 
condition. 

** The ERROR condition is raised when an error occurs that is not covered by PL/I 
exceptional conditions - taking the square root of a real negative number, for 
example. It is also raised as standard system action when handling all types of 
error conditions. Thus an ERROR on-unit enables the programmer to intercept all 
error conditions. 



Figure 7.3. (Part 2 of 2). PL/I conditions 



90 



(SIZE):B:PROC; 


ON ERROR SNAP; 


• 


• 


• 


CALLC; 




C:PROC; 


CALLD; 



D:PROC; 



CALLE; 



E:PROC; 



Static descendency : the enablement prefix (SIZE): in 
procedure B is inherited only by the contained procedure 
C, regardless of which procedure calls which. 

Dynamic descendency: the on-unit ON ERROR SNAP; is 
inherited by any procedure called by 8 and any 
subsequently called procedures. Thus, if B calls D, which 
calls E, the on-unit is established in procedure E. 



Figure 7.U. Static and dynamic descendency 
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UNQUALIFIED CONDITIONS 



QUALIFIED CONDITIONS 



1. A flag at the head of the DSA indicates that static ONCBs exist for that 
block. 

2. the block and current enable cells indicate which of those conditions that 
are under programmer control are enabled at any given point in the program. 
Each such condition is represented by a single bit in each cell. 

3. There is an on-cetl for every ON-statement in the block. Each on-cell consists 

of a one-byte code identifying the condition, e.g., X'OA' (SUBSCRIPTRANGE). 
If the Mme condition appears more than once, previous on-cells are set to 
zero. 

4. Static ONCBs are held contiguously in static storage, in the same order as the 
corresponding on-cells. They contain a code byte and flags that indicate such 
things as : whether SYSTEM was specified, whether SNAP was specified, 
whether the on-unit consists of a single GOTO statement, whether it is a null 
on-unit, etc. If there is an on-unit, its address is given in the second byte. (For 
GOTO-only on-units, the offset of the address of the label variable is given.) 



1. A flag at the head of the DSA indicates that dynamic ONCBs exist. 

2. Dynamic ONCBs are set up during execution of each block in which qualified 
condition ON-statements occur. The last two words of a dynamic ONCB 
contain the same type of information as static ONCBs (described above, under 
'Unqualified Conditions'), but use additional flags to indicate whether the 
condition is enabled and whether it is established. The second word contains 
qualifying information, such as the address of the FCB (for conditions such 
asENDFILE, RECORD, TRANSMIT, KEY, etc.), or address of a symbol 
table (for ON CHECK on-units). 

3. Dynamic ONCBs are chained together, the most recent being addressed from 
a fixed offset in the DSA. The last dynamic ONCB in the chain contains zero 
in its backchain field. 



DSA 



Enable 
cells 



On-cells 



Dynamic 
ONCB 



Flags 



Address of LWS 



Address of static ONCBs 



Dynamic ONCB chain 



Address of on-cells 



1st 



End of chain (Zero) 



Address of FCB 



Code Flags 



Address of on-unit 



Dynamic 
ONCB 



Dynamic 
ONCB 



Address of symbol table 



Flags 



Address of on-unit 



Address of FCB 
Flags 



Offset of label variable 
(On-unit is GOTO only) 



Address of label variable 





LWS 








Flags 


ONCA offset - 




^ 


1st level 






Flags 


ONCA offset 




2nd level 




Backchain to dummy ONCA 






Condition built-in 
function information 


0N( 




Address of on-unir 



Flags 



Address of on-unit 



Flags 



Not set (system action) 



2nd static 
ONCB 



3rd static 
ONCB 



Figure 7. 5. The major fields used in error handling 
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Implementation of Error Handling 



To implement the PL/I error handling scheme 
it is necessary to be able to detect all 
the PL/I conditions, to acquire various 
information about how the conditions 
occurred for condition built-in function 
values, to determine whether the condition 
is enabled and whether an on-unit is 
established, and then take the necessary 
action. 

The methods used by the PL/I optimizing 
compiler are summarized below. 

1 . Detection of the._PL/I conditions 

All PL/I conditions that correspond 
directly to program check interrupts 
are left to the detection of the 
operating system. 

A SPIE macro, issued during program 
initialization, results in control 
being passed to the error handling 
module IBMBERR. 

All other interrupts are detected by 
special checking-code, either 
generated by the compiler, or included 
in library modules. The checking- code 
calls the error handling module 
IBMBERR when a condition is detected. 

2. Acguiring information about the 
interrupt 

Information about the interrupt is 
obtained by analyzing the PSW for 
program check interrupts and by 
checking-code for software detected 
interrupts. Condition built-in 
function values are accessed through a 
control block known as the ON 
communicati ons area ( ONCA) . 

For software detected conditions, the 
ONCA is largely set up by the 
checking-code. For system detected 
conditions the ONCA is set up by the 
error handler from information in the 
PSW. 

3 . Compilation _and handling of on-units 

Certain simple on-units are 
represented by a series of flags in an 
ON control block (ONCB) , but the 
majority are compiled as independent 
program blocks to which control is 
passed from the error handling module. 

*» . Maintaining a record of enablement and 
establishment 

During execution, information 



indicating which conditions are 
enabled and which on-units are 
established is placed in the following 
control blocks: 



Enable cells - 



ON cells - 



ON control blocks 
(ONCBs) 



indicating enablement 
or disablement of the 
conditions that can be 
enabled and disabled by 
the programmer. 

indicating which 
unqualified conditions 
have established 
on-units. 

indicating address of 
on-units or action to 
be taken, and, for 
qualified conditions, 
whether the on-unit is 
established, and, for 
CHECK only whether the 
condition is enabled. 



5. Determining and directing action when 
interrupt occurs 

After every interrupt, control is 
passed to the error-handling module 
IBMBERR. 

A test is first made to see whether 
the condition is one that may be 
enabled or disabled by the programmer. 
If the condition is disabled, control 
is returned to the point of interrupt. 
If the condition is enabled, a search 
is made in all active blocks for an 
established on-unit. This is done by 
examining ON cells or ONCBs set up by 
compiled code. If an on-unit is 
found, the specified action is taken. 
If the dummy DSA is reached without 
finding an on-unit, standard system 
action is taken under the control of 
the error-handling module. 

The scheme is shown diagramatically in 
figure 7.1, and each topic is discussed in 
greater detail in the sections below. A 
summary of the uses of the various control 
blocks is given in figure 7.5, 

Figure 7.6 gives a programming example 
in which the error handling actions can be 
followed through. Figure 7.15 summarizes 
the complete error handling operation. It 
is intended for reference throughout the 
chapter and for use as a reminder by 
readers who know the basic principles. 

The handling of the CHECK condition, 
which is a special case, is treated in a 
separate section of this chapter under the 
heading "The CHECK Condition." 
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(SUBSCRIPTRANGE) : SORT: 

PROCEDURE OPTIONS (MAIN); 

ON SUBSCRIPTRANGE BEGIN; 

PUT EDIT ("SUBSCRIPTRANGE OCCURRED') (A); 

PUT SKIP DATA (l,J,K); 

/♦SUBSCRIPT VALUES FOR TEST*/ 

END; 



ON SUBSCRIPTRANGE SYSTEM; 



END SORT; 



ACTION 
DURING 
COMPILATION > 



1. Remove the on-unit from the position it holds in the 
block and treat it as a separate begin block. 

2. Generate code to set a flag in the block enable cell of the 
DSA, to indicate that SUBSCRIPTRANGE is enabled 
throughout the block. 

3. Generate code to set up two on-cells in the DSA. Set up 
two corresponding ONCBs in the static internal control 
section (one for each ON-statement in the block). 

4. Place instructions equivalent to the ON-statements in 
compiled code. The first statement causes a code byte 
corresponding to SUBSCRIPTRANGE to be inserted in 
the first on-cell; the second statement causes the same 
code byte to be inserted in the second on-cell, and sets 
the first on-cell to zero- 

5. Generate code to insert flags in the ONCBs. Insert the 
address of the on-unit in the first ONCB. 

6. Generate code to carry out the on-unit. 

7. Generate code to check for the occurrence of SUB- 
SCRIPTRANGE in every statement that could potentially 
cause the condition to be raised. 



Figure 7.6. An example of error handling 




The checking code generated by tne compiler recognizes the occurrence 
of SUBSCRIPTRANGE and passes control to the error handler, after 
placing any required condition built-in function values in the ONCA. (In 
this case only the error code is generated. ) 

The error handler checks to see if SUBSCRIPTRANGE is one of those 
conditions that can be enabled by the programmer. Since rt is such a 
condition, a check is made, in the block enable cells of the DSA, to see 
if it is enabled. {Jf it were not enabled, control would return directly to 
to the point of interrupt.) 

Finding that the condition is enabled, the error handler then goes to 
the on-cells in the DSA. These are tested, using a translate-and-test table 
in the TCA, to see if SUBSCRIPTRANGE is established. After this, the 
action depends on whether the code for SUBSCRIPTRANGE is detected 
in the first or second on-cell, and consequently whether the first or 
second ONCB is used. 

If the first ONCB is used, on-unit action is indicated; if the second ONCB 
is used, standard system action must be taken. (Standard system action 
wouU also be taken if the code for SUBSCRIPTRANGE were not found 
in the DSA on-cells of the block In which the interrupt occurred, or in 
the DSA of any dynamically encompassing block.) 



On-unit action 

1. A further allocation of library worksp>ace 
and a new ONCA are acquired in case they 
should be needed during execution of the 
on-unit. 

2. The on-unit (addressed from the ONCB) 
is executed. 

3. Provided there is not a GOTO out of the 
on-unit, return is made to the error 
handler. The error handler then carries 
out standard system action for return 
from an on-unit. 



System action 

For SUBSCRIPTRANGE, standard system 
action is to produce a message and raise , 
ERROR. The message modules are called 
to put out a message dependent on the 
error code. 

ERROR is raised, and a search is made 
through all active blocks for an ERROR 
on-unit. Since there is none, standard 
system action is again taken; this is to 
raise FINISH. Since there is no FINISH on- 
unit, the standard system action of return- 
ing to IBMBPIR is takpn, thus terminating 
the program. 



DSA of block 



Key 



Adst. static ONCB) - offset X'5C' 



A( latest dynamic ONCB) offset X'60' 



A{oncells) - offset X'70' 



Oncells 



^ 



end marker 



Oncells contain code for condition if 
on unit established otherwise 



Dynamic ONCB 
Contains code indicating condition 
qualifier and whether on-unit is 
established. Also address on-unit. 



Further dynamic ONCB 
Contents as above. Dynamic ONCBs 
are chained together. 



Object module 




Standard housekeeping 
area of DSA 



"1 
I 



I ^ 






1st. Static ONCB 



Contains address of 
on unit + other 
information 



2nd. Static ONCB 



Contents as above 



3rd. Static ONCB 
Contents as above 



On-unit 



On-unit 



On-unit. 



On-unit 



On-unit 



Broken lines show method of addressing on-units 
for q ualified conditions. The ONCBs are chained 
together and the address of the end of the chain 
held at a fixed offset in the DSA. The on-unit 
(if any) is addressed from the ONCB. 

Solid line shows method of addressing on-unit for 
unqualified condition. ONCBs are held contiguously 
in the same order as oncells, and the address of the 
first ONCB is held at a fixed offset in the DSA. By 
determining the position of the relevant oncell, the 
position of the required ONCB can be inferred and 
hence its offset from the start of the static ONCBs. 
The first oncell refers to the first ONCB etc. The 
on-unit is addressed from the ONCB. 



Figure 7.7. Addressing on-units 
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Detecting the Occurence of Conditions 



SYSTEM DETECTED CONDITIONS 



AS far as possible, the detection of PL/I 
conditions is left in the hands of the 
operating system. Those conditions that can 
be detected by the operating system are 
left in the hands of the operating system. 
The only interrupt that is masked out in 
the PSW is the significance interrupt. 
Regardless of the enablement or disablement 
of PL/I conditions no other interrupts are 
inhibited- 

When a condition is detected by the 
system, a SPIE macro, executed during 
program initialization, causes control to 
be passed to entry point A of the error- 
handling module IBMBERR. The address of 
this point is held in the TCA appendage. 
When entered by this entry point the error 
handler equates the interrupt with a PL/I 
condition and passes control to the main 
error handling logic of the module. The 
relationship between PL/I conditions and 
system interrupts is shown in figure 7.2. 



functions and places these values, or their 
addresses in a control block known as the 
ON communications area (ONCA) . 

When these actions have been carried out 
a call is made to entry point B of the 
error handling module IBMBERR. The address 
of this entry point is held at offset X'78' 
in the TCA. 



detect ing_I/0_Conditions 



The TRANSMIT and the ENDFILE condition are 
normally detected by the data management 
routines rather than by PL/I code. When 
this occurs the error or end-of-file 
routine in the PL/I transmitter modules 
receives control and passes it to the error 
handler via a special I/O error module. 
This I/O error module contains the 
necessary code to set up the interrupt 
control block, including the error code and 
the qualifier. These conditions can, 
therefore, be considered to be software 
detected. Further detail is given in 
chapter 8 - Record Oriented Input/Output. 



SOFTWARE DETECTED CONDITIONS 



EXECUTING SIGNAL STATEMENTS 



During compilation, the compiler analyzes 
the conditions enabled for each block and 
statement and ensures that the necessary 
checking code will be executed. The 
checking code may be specially generated by 
the compiler, or it may be included in 
library modules that will be called when 
the particular condition is enabled. The 
method used for checking for each condition 
is shown in figure 7.3. 

As far as possible the checking code is 
not included in the program if the 
condition that it checks for is not 
enabled. However, every library module 
contains the checking code for detecting 
any PL/I condition that can occur in the 
module. In certain circumstances, 
therefore, code to check for software 
detected conditions will be executed and a 
call made to the error handler even though 
the condition is disabled. 

When an interrupt has been detected 
during execution, the checking code sets up 
a parameter list for the error handling 
module IBMBERR. This parameter list, known 
as the interrupt control block, contains a 
code that defines the type of interrupt 
that has occurred and, if the condition is 
qualified, contains a means of identifying 
the qualifier. The checking code also 
calculates the value of relevant built-in 



SIGNAL statements take the same form as 
software detected interrupts, they are 
executed by a call to IBMBERR with the 
appropriate interrupt control block. The 
error code in the interrupt control block 
will indicate, to the error handler, the 
type of condition signalled, and the fact 
that the condition was signalled. The call 
to the error handler is made to entry point 
B, regardless of whether the condition is 
normally detected by system or software. 

It is necessary for the error handler to 
know that the condition was signalled, 
because different action may be required if 
the interrupt was signalled when computing 
certain built-in function values. 



PASSING INFORMATION ABOUT INTERRUPT 



When the error handling is entered it must 
be able to access information about the 
interrupt. This information must identify 
the type of condition that has occurred and 
further identify the interrupt so that the 
most useful diagnostic message can be 
generated. Any relevant built-in function 
values must also be available, plus the 
default values for any built-in functions 
that are not relevant to the type of 
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interrupt. 

When the interrupt is software detected, 
some of the information is set up in the 
checking code before control is passed to 
the error handler. When the interrupt is 
system detected, the PSW is used and the 
error handler interprets the information in 
the PSW, setting up information in a format 
similar to that produced by the checking 
code. This allows the main logic of the 
error handler to treat program checks and 
software detected condition in the same 
manner. 

The parameters passed to the error 
handler by compiled code are known as the 
interrupt block, and take the following 
format : 



The two byte error code is raised only 
for the ERROR condition. The ERROR 
condition is raised for those interrupts 
and errors that have no directly associated 
PL/I condition. Certain of these, such as 
taking the square root of a real negative 
number, are software detected. Others are 
associated with program check interrupts 
such as a data interrupt. 

When the error condition is to be raised 
a two byte code only is generated. The 
value in this code corresponds with a table 
held in the error handler which identifies 
the cause of the interrupt. 



Condition Built-in Functions 



Word 1 



Error code 



Word 2 Qualifier if any 

Words 3,4 and 5 

extra information used in 
handling CHECK 

The error code defines the type of error. 
The qualifier gives a method of identifying 
the qualifier for qualified conditions. 
For I/O conditions the address of the 
DCLCB, is used as a qualifier. The address 
of a symbol table, control section, or 
pseudo register offset is used for other 
qualified conditions. 

The address of software detected 
interrupt is taken from the register 14 
value when the error handler is called with 
a BALR 14, 15. This value is stored in the 
DSA by the prologue of the error handler. 
When the interrupt is system detected the 
address is taken from the PSW. 



Error Code 

The error code is either a two or four byte 
code that defines the reason for the 
interrupt. For all conditions except the 
error condition a four byte code is passed. 
For the errors that will immediately raise 
the ERROR condition only a two byte code is 
passed.- 

The four byte code is made up as follows: 

Byte 1 identifies PL/ I condition 

Byte 2 identifies causes of condition 

Byte 3 6 4 identify those ON built-in 

functions that are valid for the 
condition. 



Certain condition built-in function values 
are implicit in the information that is 
passed to the error handler. ONCODE, for 
example, bears a direct relationship to the 
error code. Other values, such as ONCHAR 
and ONSOURCE must be calculated when the 
interrupt occurs. These values or the 
addresses of the values are placed in the 
ONCA. The ONCA is addressed from library 
workspace. The address of library 
workspace is held at a fixed offset in 
every DSA. ONCODE, ONLOC, and ONFILE are 
not generated by. the checking code as their 
contents are implicit in the information 
passed to the error handler. 

The ONCODE is deduced from the error 
code and, when required, a transient 
library module IBMBEOC is called to 
translate the error code into the ONCODE. 
Both an error code and an ONCODE are used 
as it is possible to define the error mere 
accurately than can be done with the 
ONCODES, which must be kept compatible with 
other PL/I compilers. Thus the error code 
allows a more useful diagnostic message to 
be generated than would be possible if only 
the ONCODE was generated. 

The ONLOC value is also calculated by a 
separate module. ONFILE is accessed from 
the DCLCB. Both ONLOC and ONFILE are 
placed in the ONCA only if an on-unit is to 
be entered. Similarly if an on-unit is to 
be entered the error code is placed in the 
ONCODE field of the DSA. If the ONCODE 
value is required in the on-unit the module 
IBMBEOC is called to calculate the ONCODE 
from the error code. 



Chain of ONCAs 



PL/I allows access to condition built-in 
function values when no condition has 
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00 



PROGRAM FLOW 



MAINLINE CODE 



CONVERSION 
occurs ONCHAR 
& ONSOURCE 
addresses placed in 
1st ONCA 
Error code placed 
in ONCODE field 




Continuation of mainline code 



CONVERSION 
on-unit entered. 
New ONCA 
acqu ired 



CONVERSION 
ON-UNIT 



:2 



NAME condition 
occurs. 
DATAFIELD 
address placed 
in second ONCA. 
Error code placed 
in ONCODE field. 



Continuation of on-unit 



NAME on-unit 
entered. New 
ONCA acquired. 



NAME 
ON-UNIT 



MAINLINE' 
CODE 



GOTO causes 
return to 
mainline code 



CHAIN OF ONCAs 
Dummy ONCA 



Holds all default 
values or their 
addresses 



Dummy ONCA 



Dummy ONCA 



Dummy ONCA 



1st. ONCA 
J 

Ready for use 



_ J 







Holds all default 
values or their 
addresses 






1st. ONCA 






ONCODE, 
ONCHAR, & 
ONSOURCE fields 
filled in 




-1 


2nd ONCA 

1 



Holds all default 
values or their 
addresses 



1st. ONCA 



I Ready for use i 
I I 



ONCODE, 
ONCHAR, & 
ONSOURCE fields 
filled in. 



2nd. ONCA 



ONCODE & 
DATAFIELD 
filled in. 





Holds all default 
values or their 
addresses 




1st. ONCA 




ONCODE, 
ONCHAR, & 
ONSOURCE fields 
unaltered. Will be 
overwritten if there 
is a further 
interrupt 



3rd. ONCA 



Ready for use. 



All condition built in functions 
accessed from dummy ONCA 



ONCODE, ONCHAR, and ONSOURCE accessed from first 
ONCA. All others from dummy ONCA 



ONCODE and DATAFIELD accessed from second ONCA. 
ONCHAR and ONSOURCE accessed from first ONCA. 
All others from dummy ONCA. 



On return from an on-unit all unnecessary 
ONCAs are discarded as they are in the 
LIFO stack. The current ONCA retains the 
previous interrupt information until over- 
vwitten. Values are taken from the dummy. 



Figure 7.8, Accessing a built-in function value from the chain of ONCAs 



occurred or when a condition has occurred 
in which the built-in function is invalid. 
The rule is, that the built-in function 
value given will be the most recent value 
in an active ONCA or the default value. To 
allow for this, ONCAs are chained together 
and the end of the chain is the dummy ONGA 
that is set up in the program management 
area during program initialization. The 
dummy has the same format as other ONCAs 
and contains the default values or pointers 
to the default values for all built-in 
functions . 

For every interrupt that occurs, a new 
ONCA is acquired. This means that, should a 
condition occur within an on-unit, an ONCA 
will be available in which to place any 
relevant built-in function values or their 
addresses. A new allocation of library 
workspace (LWS) is also required for use 
during the on-unit. 

When a built-in function value is 
required, the ONCA before the current ONCA 
is inspected. The current ONCA is unused 
as it is ready for a new set of values. 
Each ONCA is headed by flags that indicate 
which built-in functions are given in the 
ONCA. When the required built-in function 
value is flagged as invalid, a chain back 
is made to the previous ONCA. As all 
fields are valid in the dummy, the default 
will be used if there have been no 
interrupts for which the function is valid. 

In the program below, an example of the 
chain of ONCAs is shown. The ONCHAR 
reference in the NAME on-unit would be 
valid if the NAME condition was raised in 
the CONVERSION on unit. The correct value 
would be accessed after chaining back to 
the ONCA associated with the CONVERSION 
interrupt. 

In other circumstances the default value 
would be accessed from the dummy ONCA. 



A situation that could occur in this 
program, and the associated chaining of 
ONCAs are shown in figure 7.8. 

When an on-unit is completed, the latest 
generation of LWS and the ONCA are deleted 
immediately control returns to a block 
before the error handler. This is because 
they are held as VDAs associated with the 
error handler's DSA. When control leaves 
the error handler, the current ONCA will 
contain the interrupt information for the 
original interrupt. This information 
remains until the ONCA is freed or a 
further interrupt occurs, in which case it 
is overwritten. (See figure 7.8.) 



Establishment and Enablement 
Information 



(Executing ON Statements) 

Establishment and enablement information is 
set up and updated by compiled code. 
Enablement is indicated by a set of flags 
known as the "current enable cells," which 
are held in every compiled code DSA. 
Establishment for unqualified conditions is 
indicated by a further series of bytes in 
the DSA known as the "ON-cells." 
Establishment for qualified conditions is 
indicated in flags in dynamic ONCBs. 
Dynamic ONCBs are held in the DSA of the 
block in which the associated ON-statement 
occurs. 

To alter the enablement for the duration 
of a statement or to execute an ON 
statement, compiled code alters the 
appropriate fields mentioned above. 



ENABLEMENT 



CHAIN: PROC OPTIONS (MAIN) ; 

ON NAME BEGIN; Z+NAME ON 

UNIT*/ 

PUT DATA(ONCHAR); 

GOTO LABELl; 
END; 

ON CONVERSION BEGIN; 
/♦CONVERSION ON UNIT*/ 

GET DATA ( A, B, C) ; 



END; 
LABELl: X=Y+2; 

END CHAIN; 



Enablement is indicated in the current 
enable^cells , a two byte field held at 
offset X'56^ in the DSA. Each condition 
whose enablement is under programmer 
control has a bit allocated to it. The 
conditions associated with each bit are 
shown in figure 7.9. 

The CHECK condition has three bits 
associated with it. This is because the 
CHECK condition can be used both as a 
qualified and as an unqualified condition. 
Bit zero indicates that CHECK is enabled, 
either qualified for one or more variables, 
or unqualified for all variables. Bit 11 
indicates that CHECK has been enabled or 
disabled as an unqualified condition. Bit 
10, only valid if bit 11 is set, indicates 
whether the unqualified CHECK is enabled or 
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1 Bit 





CHECK* 


1 Bit 


1 


ZERODIVIDE 


1 Bit 


2 


FIXEDOVERFLOW 


1 Bit 


3 


SIZE 


1 Bit 


H 


CONVERS ION 


1 Bit 


5 


OVERFLOW 


1 Bit 


6 


UNDERFLOW 


1 Bit 


7 


STRINGS IZE 


1 Bit 


8 


STRINGRANGE 


1 Bit 


9 


SUBSCRIPTRANGE 


i Bit 


10 


CHECK* 


1 Bit 


11 


CHECK* 


1 ♦ See section "The CHECK C 


I details 





Figure 7.. 9. Meaning of enablement bits 



disabled. (See later section in this 
chapter "Handling the CHECK condition for 
further details. ) 

A further two byte field in the DSA held 
at offset X*54* is known as the block 
enable_cells. This field is similar to the 
current enable cells and holds a record of 
the enablement at the start of the block. 

Both current enable and block cells are 
set up by the prologue code. If the 
enablement is altered for the duration of a 
statement, the appropriate bit in the 
current enable cells is altered at the 
start of the statement. At the end of the 
statement the bit is reset to its previous 
value. If there is an interrupt during the 
execution of the statement, on- unit action 
may return control to another part of the 
block where different conditions are 
enabled. The block enable cells are 
necessary to allow for this. Whenever a 
GOTO out- of -block occurs in an on-unit the 
GOTO code in the TCA resets the current 
enable cells from the block enable cells. 
This ensures enablement will be correct, 
regardless of the situation when control 
left the block. 



Qua lified C onditions 



The only qualified condition whose 
enablement is under programmer control is 
the CHECK condition. As CHECK is a special 
case it is treated in detail elsewhere. 
The principle involved however is that 
enablement for any particular qualifier is 
given in a dynamic ONCB and, to discover 
whether CHECK is enabled for a particular 
item, a search must be made in the DSA 
chain for a relevant dynamic ONCB, 



ESTABLISHMENT - EXECUTING ON AND REVERT 
STATEMENTS 



For establishment the situation differs 
between qualified and unqualified 
conditions. This is because at any one 
point in the program there can only be one 
established on-unit for an unqualified 
condition but there can be an unlimited 
number of established on-units for 
qualified conditions. In a program with a 
number of files, for example, the 
programmer may wish to take different 
action when the end of the data is reached 
in each of the files. Consequently there 
could be an established ENDFILE on-unit for 
each file. 

On-units are established by the 
execution of an ON statement. Once it has 
been discovered that an on-unit is 
established it is then necessary to access 
the on-unit. Access to the address is made 
through a control block known as the ON- 
control block ONCB. For unqualified 
conditions, ONCBs are set up during 
compilation in static internal storage and 
are known as static ONCBs^ For qualified 
conditions, ONCBs are set up (by compiled 
code) in the DSA and are known as dynamic 
ONCBSi. See figure 7.7. 



Qualified^ Conditions 



The establishment of qualified conditions 
is indicated directly in the ONCB. All 
dynamic ONCBs for a block are chained 
together and address of first ONCB on the 
chain is held in a field at offset X'60' in 
the DSA. (See figure 7.8.) 

Dynamic ONCBs contain a code indicating 
the condition type, flags to indicate 
whether the condition is enabled and 
whether the associated on-unit is 
established, a method of identifying the 
qualifier, and, either the address of the 
compiled code on-unit, or flags indicating 
the action specified in the source program 
on-unit. There is an ONCB for every ON 
statement in the block that refers to a 
qualified condition. 

ON and REVERT Statements; When the ON 
statement is executed the appropriate 
dynamic ONCB is set up, chained, and the 
establishment bit in the ONCB is set 'on* 
by compiled code. For second and subsequent 
ON statements or REVERT statements for the 
same condition and qualifier, the 
information in the ONCB (flags and address 
of on-unit) is altered. 
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Software interrupts 
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'^andard system action and action for normal return takes one of the forms 
shown below depending on the condition that caused the interrupt and 
swhether the interrupt was signalled. Messages are generated for some conditions. 
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* Special on-units are not entered these are: null on-units, or on-units containing only a SNAP or SNAP SYSTEM instruction. 
Figure 7.10. Simplified flowchai^ of IBMBERR 
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Ungualified Conditions 



For unqualified conditions establishment 
information is held in a series of one byte 
fields known as oncells. There is one cell 
for each ON statement in the block and, 
consequently, for each ONCB associated with 
the block. ONCBs for unqualified 
conditions are held contiguously in static 
internal storage in program block order. 
(See figure 7.8. ) 

In each DSA containing ON statements an 
area is reserved for ON cells. Cells are 
one byte fields that correspond one-for-one 
with the static ONCBs for that block. The 
first ONCB for the block is addressed from 
offset X''5C' in the DSA. ON cells are 
initialized to zero by the prologue code. 
When the ON statement associated with the 
on- unit is executed, a code is set in the 
ONCELL indicating the condition type. The 
error handling module searches for an 
established on unit by testing the ON cells 
in the DSA of each active block until, 
either an active ON cell for the condition 
is found, or the major task dummy DSA is 
reached. When an active ON cell is found, 
the number of ON cells in the block 
preceding the active ON cell are 
calculated. The associated static ONCB will 
be in the same relative position. As all 
ONCBs for unqualified conditions are the 
same length the address of the requested 
ONCB can be determined and the action to be 
taken decided from the ONCB. 

ON and REVERT Statement; When an ON 
statement is executed a code indicating the 
condition type is set in the appropriate ON 
cell. If there was a previous ON statement 
for the condition the former ON cell is set 
to zero. For REVERT statements any ON cell 
referring to the condition is set to zero. 

If there is more than one ON-statement 
for the same condition in a block, the 
flags in the previous ON cell will be set 
off when second and subsequent ON cell 
flags are set on. The REVERT statement is 
executed by setting the flag in the latest 
ON cell to zero. The situation then 
reverts to that at the start of the block. 



HANDLING ON-UNITS 



On-units, except certain single-statement 
on-units, are treated as separate program 
blocks by the compiler. They are separated 
from the ON statement and compiled with 
prologue and epilogue code. The address of 
the on-unit is placed in an address 
constant. The ON statement remains in its 
logical place in the program and sets 



either the ON cell or a flag in the dynamic 
ONCB, to indicate that the associated on- 
unit is established. 

In order to save the overhead of 
executing prologue and epilogue code, 
certain single-statement on-units are not 
compiled. Instead the action required is 
indicated by flags in the ONCB and is 
carried out under the control of the error 
handling module. 

The types of on-unit involved are: 

1. Null on-units. 

2. On-units containing only SNAP, SNAP 
SYSTEM, OR SYSTEM options. 

3 . On units containing only a GOTO 
statement. 

The presence of these on-units is indicated 
by flags in the associated ONCB. For the 
GOTO only on-unit, the ONCB also contains 
the offset in the DSA of the label variable 
or label temporary to which the GOTO is to 
be made. 



The Logic of the Error Handler 



A simplified flowchart of the error 
handling module IBMBERR is given in figure 
7.10. This flowchart shows the action 
during the handling of an interrupt and 
includes execution of an on-unit. The 
logic is described below. A complete 
description is given in the licensed 
program product document OS PL/I Resident 
Library Program Logic. 



IBMBERR - ERROR- HANDLING MODULE 



The error-handling module, IBMBERR, handles 
three situations. These are: 

1. Program check interrupts. 

2. PL/I conditions detected by the object 
program. 

3. Errors detected by the object program 
that are not directly related to #PL/I 
conditions and which raise the ERROR 
condition. 

All three situations are ultimately dealt 
with as PL/I conditions. For example, the 
FIXEDOVERFLOW condition would be raised 
when fixed point overflow occurs and causes 
a program check interrupt. Where there is 
no directly-applicable, PL/I condition (for 
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instance after a data interrupt) a system 
message is printed and the ERROR condition 
is raised - 



PROGRAM CHECK INTERRUPTS 



Before a program check interrupt can be 
handled as a PL/ I condition, action must be 
taken to prevent the system terminating the 
job should a further program check 
interrupts occur. This is done by altering 
the old program PSW and returning out of 
the SPIE exit code so that it appears to 
the system that the interrupt has already 
been handled. The second word of the PSW 
passed to ERR in the PIE (program interrupt 
element) containing the interrupt address 
is stored in the register 15 field in the 
save area which was current when the 
interrupt occurred. IBMBERR then changes 
the address in the PSW in the PIE to an 
address in IBMBERR. Control then passes 
via the supervisor to the address in 
IBMBERR that has been inserted in the PSW. 
Handling of the interrupt consequently 
appears to the supervisor to be finished. 
The address, in the field in the TCAj, to 
which control will pass after a program 
check interrupt is then changed to 
IBMBERRC. Should an interrupt now occur 
during the execution of IBMBERR, control 
will pass to IBMBERRC, which terminates the 
job. 

The first task is to generate a suitable 
error code that will equate the interrupt 
with a PL/I condition. The floating point 
registers are saved in IBMBERR' s DSA, if 
the interrupt is one corresponding to a 
PL/I condition, and control can then be 
passed to the main PL/I condition-handling 
routine described in the next section. 
There are, however, three special cases 
that require further action. These are: 

1. If the interrupt was floating point 
underflow, then the doubleword in 
which the floating point register 
which underflowed was stored is set to 
zero. 

2. If fixed point overflow, exponent 
overflow, decimal overflow, or fixed 
point divide has occurred, then it may 
correspond to the PL/I condition SIZE 
and not to FIXEDOVERFLOW or 
ZERODIVIDE. If this is possible, a 
flag will have been set in the program 
check interrupt qualifier in the TCA. 
A test of this flag is therefore made 
and the necessary action taken, SIZE 
being raised if it is enabled. 

If the interrupt was an operation 
interrupt it may have been caused by 



an extended floating point instruction 
being used on a machine that does not 
have the extended float instruction 
set. If this is the case, the 
instruction may require simulation. 
The error handler therefore passes 
control to a module IBMBEEF that 
interfaces with the extended float 
simulator lEXPSIM. IBMBEEF passes 
control to the extended float 
simulator which returns the correct 
result if the statement was valid, or 
a return code if the statement was 
invalid. If the statement is valid 
IBMBEEF returns control to the point 
of interrupt. If the statement was 
invalid IBMBEEF returns control to the 
error handler. 

For those installations that do not 
require extended float simulation a dummy 
version of IBMBEEF is available. This 
module returns control directly to the 
error handler and the error condition is 
raised. 



SOFTWARE INTERRUPTS 



When the main condition-handling logic is 
reached, an error code will have been 
generated to indicate the type of error or 
condition that has been raised. For 
program check interrupts, the code is 
produced by the error module itself. For 
errors or conditions detected by the object 
program, the object program sets up this 
code. When the "object program has detected 
the error, this will, in some cases, 
correspond to a PL/l condition. However, 
there are certain errors (such as 
attempting to take the square root of a 
real negative number) that do not have 
directly-related PL/I conditions. For PL/I 
conditions, a four-byte code is passed. 
For other errors, the code consists of only 
two bytes. For the two byte code, the 
first byte indicates which class of error 
has occurred. For the four byte code, the 
first byte is the identifier of the PL/I 
condition being raised (the same identifier 
is used in on-cells) . 

The error-handling module checks the 
first byte of the code to see whether it is 
handling ERROR or another PL/I condition. 
If the code indicates ERROR, then the 
message module IBMBESM is loaded into a VDA 
and called. This module prints the relevant 
diagnostic message; a suitable four-byte 
code is then generated. The situation is 
then treated as for any other PL/I 
condition. 

The second two bytes of the code passed 
when a PL/I condition has been raised 



Chapter 7: Error and Condition Handling 103 



indicate which condition built-in functions 
are relevant to the condition. If the 
condition is one that needs to be 
qualified, the qualification is also 
passed. 

When a PL/I condition error code is 
passed, action depends on whether the 
condition is one of those that can be 
disabled by the programmer. If it is such a 
condition, a test is made in the current 
enable cells of the DSA. If the condition 
is not disabled, then a search for a 
relevant established on-unit must be made. 
If the condition is disabled, a return is 
made to the point of interrupt. To find 
established on-units, a test is first made 
in the action byte to discover whether the 
condition is qualified. If the condition 
is not qualified, a search is made through 
the on-cells of all active blocks to find a 
match for the number in the first byte of 
the code passed to IBMBERR. This is done 
with a translate-and^test instruction using 
the TRT table addressed from offset X'lC 
in the TCA. When found, the position of the 
located on-cell gives the position of the 
associated ONCB. A test can then be made 
to determine the action to be taken. 

If the condition is qualified, a search 
for an active matching ONCB is carried out 
through the chain of dynamic ONCBs held in 
the DSAs. 

If the major task dummy DSA is reached 
without a match being found, then standard 
system action is taken. This action is 
defined in IBMBERR. When a matching active 
ONCB is found, tests are then made, as 
follows, on the flags in the ONCB. 

Test 1. SNAP specified? If so, the 
message module IBMBESM is 
dynamically loaded and a SNAP 
message printed. 

Test 2. Is SYSTEM specified? (This can 
occur when "ON condition SYSTEM" 
has been specified. ) If SYSTEM is 
specified, then the action in 
IBMBERR is taken. 

Test 3. Does the on-unit consist only of a 
GOTO statement? If so, then the 
GOTO is executed without entering 
an on-unit. This saves the 
housekeeping involved in entering 
an on-unit. 

Test U. Is the on-unit a null on-unit? If 
so, then the action on a normal 
return from the on-unit is taken. 

If none of these is positive, then it is 
necessary to enter the on-unit. 

Before entering the on-unit, the 



following action must be taken. A new 
allocation of library workspace must be 
initialized and its address put into the 
standard offset in the DSA of IBMBERR. 
This provides workspace for any further 
library modules that may be called. Tests 
must be made to see that the ONCA is 
correctly set-up for any built-in functions 
that may be used. The address in the PICA 
field which was altered to the error 
handler, must also be altered to its 
original setting so that program check 
interrupts will cause entry to be made to 
the error handler by the entry point 
IBMBERRA rather than IBMBERRC. This 
ensures that the action specified by the 
PL/I program is taken if a program check 
interrupt occurs during the execution of an 
on-unit. 

Normal return from the on-unit to 
IBMBERR is made by a branch on register 14. 
Depending on the condition, a return to the 
interrupted program is then made, or some 
special action may be taken. Four PL/I 
conditions cause action other than return 
to be taken. 

1 . ERROR 

If the condition was the ERROR 
condition, then the FINISH condition 
is raised. 

2. FINISH 

If the FINISH condition is raised then 
a return code is set in the correct 
field of the TCA, and GOTO performed 
to the termination routine IBMBPIR. 
(If FINISH is signalled, then return 
is made to the point of interrupt.) 

3. CONVERSION 

If CONVERSION was raised, then a test 
is made in the ONCA, and if either 
ONSOURCE or ONCHAR has been accessed, 
control is passed to the address 
contained in the retry slot in the 
ONCA. The conversion is then 
attempted again. If the field has not 
been changed, then the ERROR condition 
is raised. 

4 . ENDPAGE 

If ENDPAGE was raised, then a return 
code is set in register 15 to indicate 
that an on-unit has been entered. 



RETURN TO POINT OF INTERRUPT 



Software Interrupts 



If the condition was one that was detected 
by compiled code, then a return to the 
point of interrupt is made by a branch on 
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register 14. 



Raising_the Check_Conditipn 



Program _Check_Interrugts 



For program check interrupts, the status 
of the program at the original point of 
interrupt has to be restored before return 
to the point of interrupt can be made. 
This means that the contents of the system 
save area must be reset, so that they are 
identical with those saved after the 
original interrupt. (The PSW and the 
register values were saved in the DSA at 
initial entry to IBMBERR.) 

The method used is as follows. The 
address in the PICA is altered so that the 
address that is to be branched to, after a 
program check interrupt, is changed from 
IBMBERRC to another point in IBMBERR. An 
interrupt is then caused, and the 
supervisor gains control, consequently, 
the address in IBMBERR is reached with the 
address of the system save area in register 
1. The contents of the save area and the 
PSW are then changed to those that were 
current after the original interrupt. The 
point of entry for program check interrupts 
is then reset to IBMBERRA. Return is made 
to the address in the PSW, which is that of 
the original interrupt. 



THE CHECK CONDITION 



The CHECK condition has to be handled in a 
different manner to other conditions. This 
is because it can be used as a qualified or 
unqualified condition and its enablement is 
under programmer control. 

The CHECK condition is disabled by 
default and is enabled by writing a CHECK 
prefix. It can be disabled for the duration 
of a statement or block by the NOCHECK 
prefix. Prefixes can take the form (CHECK) 
or (NOCHECK), or the form (CHECK (A, B)) or 
(NOCHECK (A, B) ) . When no name list is 
appended, the CHECK applies to all the 
relevant names in the program. An ON- 
stateroent may also be written as either ON 
CHECK or ON CHECK(A,B). ON-statements are 
independent of prefixes and may be included 
in a block to which no prefix applies. A 
qualified on-unit can be used with an 
unqualified prefix and vice- versa. 

Throughout this discussion, CHECK and 
NOCHECK without a name list are referred to 
as unqualified. CHECK or NOCHECK with a 
name list are referred to as qualified. 



CHECK is normally raised by compiled code. 
This is done by inspecting the source 
program and generating calls to the error 
handler at appropriate points. As 
enablement is statically descendent, it is 
possible to tell during compilation at 
which points CHECK is enabled and 
consequently at which points the calls to 
the error handler have to be made. 
However, for GET DATA statements there is 
no means of knowing which items will be 
passed in the data stream, and if the CHECK 
condition is enabled for any variable that 
could be read in, it is necessary to check 
every variable in the input stream to see 
whether CHECK is enabled for that variable. 
Consequently, when a GET DATA instruction 
is being executed, it is necessary for the 
error handler to test to see if the CHECK 
condition is enabled. 

With the exception of the CHECK 
condition, all conditions whose enablement 
is under programmer control are 
upgyglj^f igj* Consequently, their 
enablement or disablement can be indicated 
by one bit in the enable cells. This is 
because there are only two possibilities. 
Either the condition is enabled or it is 
disabled. With qualified CHECK, however 
there are many possibilities, because CHECK 
may be enabled for some variables and 
disabled for others, consequently, the 
enable cells are used in a different iranner 
for the qualified CHECK condition, and the 
enablement of qualified CHECK for any 
particular name is given in an ONCB. 

When the CHECK condition is raised, the 
error handler has the following tasks. 

1* Test to see if CHECK occurred durin g 
the execution of a GET DATA st ateme nt. 
If so tests for enablement must be 
made. If not continue with step 3. 

2« Test to see if CHECK is enabled. This 
involves a search along the static 
backchain to determine, for each 
block, first, if qualified CHECK is 
enabled or disabled for~the particular 
name for which CHECK was raised, and 
then, if unqualified CHECK is enabled 
or disabled. 

3* Search for a qualified established 

on- unit. This involves searching the 
dynamic backchain for a relevant 
dynamic ONCB. 

**• if £ll§£§ i§ S2 qualified established 
SSzUSife sS§E£h for an unqualified 
established on-unit. This involves a 
further search of the dynamic 
backchain looking for appropriate 
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on-cells. 



searching for Established On-Units 



5« If 112 established on- unit is found, 
taM standard systern action. 

This process is illustrated in figure 7.11. 



Tes t ing_ f or _Enab lement 



There are three bits that refer to CHECK in 
the enable cells; they have the following 
significance: 

Bit 



When it is known that CHECK is enabled, a 
search must be made for established on- 
units. This search is separate from the 
search for enablement. A. return is first 
made to the DSA in which the interrupt 
occurred. 

Two searches are made, the first for a 
qualified on-unit. The complete dynamic 
backchain is searched for relevant ONCBs. 
If one is not found, a search is made 
through the backchain for enable cells that 
indicate unqualified CHECK. If nothing is 
found, standard system action is taken. 



Standard System_Act ion 



•O'B CHECK is enabled for certain items 
in this statement 

•I'B CHECK is disabled for this 
statement 

Bit 10 (only valid if bit 11 is set) 

•0*B The unqualified prefix that applies 
is NOCHECK 

•1»B The unqualified prefix that applies 
if CHECK 

Bit 11 

•O'B No unqualified prefix applies to 
this statement 

•1*B An unqualified prefix applies to 
this statement 

Throughout this discussion Bit is 
referred to as the "any-CHECK" enablement 
bit, and bits 10 and 11 as the "unqualified 
CHECK enablement bits." Enablement and 
disablement of qualified CHECK is indicated 
in the flag bits of the ONCB. 

The test for enablement begins by a test 
on the any- CHECK bit in the enable cell. 
If this is set to zero, control is 
immediately returned to the caller. If the 
bit is set on, a search is made for a 
relevant qualified ONCB in the DSA of the 
block in which the interrupt occurred. If 
no such ONCB is found, the unqualified 
CHECK enablement bits are tested for 
unqualified enablement or disablement. If 
bit 11 is not set, neither an unqualified 
CHECK nor an unqualified NOCHECK applies, 
and a further search must be made in the 
preceding DSA on the static backchain. If 
the dummy DSA is reached without any of the 
tests proving positive, CHECK is disabled. 



Standard system action for CHECK is taken 
under the control of a special module 
IBiyiBERC. This module acquires the 
necessary symbol table address or 
addresses, places them in a VDA and passes 
control to the stream I/O initializing 
routine and, on return, to the data 
directed director module IBMBSDO. On 
completion of the operation IBMBERC returns 
control to IBMBERR. 



Error Messages 



The library module IBMBESM is called by the 
error handler to transmit the system 
messages and find the on-code value by 
calling the ONCODE routine IBMBEOC; control 
is then passed to IBMBESN to finish the 
system message, or to go to generate the 
SNAP message if required. The text for the 
messages is taken from a series of message 
text modules. The particular message text 
module required and the message within the 
module are determined from the error code. 



Message. Formats 



System Messiages : For non-PL/I conditions, 
system messages have the following 
form; 

IBMxxxx • ONCODE '= xxxx message text 
[qualifier] IN STATEMENT xx AT/NEAR 
OFFSET XXX IN PROCEDURE WITH ENTRY 
xxxx 

The qualifier might, for example, consist 
of the file name. For PL/I conditions, the 
format of the message is much the same, but 
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the name of the condition is also given. 
For example: 

IBM4 021 •ONCODE'= 3100 • FIXEDOVERFLOW 
CONDITION RAISED IN DECIMAL DIVIDE IN 
STATEMENT 31 AT OFFSET 000A35 IN 
PROCEDURES WITH ENTRY ZERNES 

Snap Messages; If an on-unit contains both 
SNAP and SYSTEM,, the resulting message is 
essentially the system message followed by 
the line 

FROM (STATEMENT/OFFSET) xxx IN A 
(BEGIN BLOCK/PROCEDURE WITH ENTRY 
xxx/ A 'xxxx' ON- UN IT) 

which is repeated as many times as 
necessary to trace back to the main 
procedure. If an on-unit contains only 
SNAP, the message begins 

•xxxxxxx* CONDITION RAISED [IN 
STATEMENTxxx] (AT/NEAR) OFFSET xxx IN 
PROCEDURE XXX 

and continues as for a SNAP SYSTEM message. 

The statement number is not always 
present in messages as the generation of 
execution-time statement numbers by the 
compiler is a compiler option. 

When statement numbers are generated, 
they are held on a block basis. For each 
block or procedure, a table in static 
storage relates each statement number to 
the offsets of the corresponding 
instructions in compiled code. A field at 
a fixed offset each entry point gives the 
address of the relevant table. 

The statement number is held in relation 
to its offset from the main entry point. 
Since the PL/I program need not have 
entered via this entry point,, the offset is 
calculated independently from that given in 
the message. If the FLOW option is used, 
then additional information is printed out 
after every snap message. (See "The FLOW 
Option," later in this chapter.) 



Interrupts in Library Modules 



When an interrupt occurs in a library 
module, the system message does not give 
the offset from the start of the library 
module, but gives the statement number of 
the statement in which the library module 
was called and the offset of this statement 
from the entry point of the procedure block 
in which it is contained. 



IdentifYing_the Erronegus^Statement 



The address required to identify the 
erroneous statement is always the address 
held in the register 14 field in the most 
recent compiled code DSA. 

If the interrupt was a software 
interrupt in compiled code, the address 
will be the return address that was used by 
the BALR instruction when IBMBERR was 
called. 

If the interrupt was a program check 
interrupt in compiled code, the address of 
the interrupt will have been moved from the 
old PSW and placed in the register 14 field 
by IBMBERR to simplify return to the point 
of interrupt. 

If the interrupt was in a library 
module, the address required is the point 
in compiled code at which the library 
routine was entered. This will have been 
placed in the register 14 field when the 
library module was called. 



Identif Ying__Entry Point Name and 

Statement Number 



The address of the entry point of the block 
is found by chaining back along the DSAs to 
the DSA before the last compiled code DSA. 
The address of the entry point used before 
the interrupt is held in the save area of 
this DSA as the branch register contents. 
The dummy DSA ensures that a chainback can 
be made from the main procedure DSA. 

The name of the entry point is found by 
chaining back one DSA beyond the first 
procedure-DSA reached. This DSA holds the 
address of the procedure-DSA entry point in 
the register 14 slot of its register save 
area (offset X'lO* from the head of the 
DSA) . The length of the name is held in a 
one-byte field immediately preceding the 
entry point. The name immediately precedes 
the length field. 

Statement numbers are generated 
separately for each external procedure, and 
the statement number table holds offsets 
from the first entry point in the external 
procedure. 

When the statement number table is link- 
edited, the address of this entry point is 
placed at the head of the table. 
Consequently, the required offset can be 
found by comparing the address of the 
statement causing the error with the 
address of the first entry point held in 
the statement number table. 
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If the NUMBER option is in force, the 
numbers are held in four byte form preceded 
by a half word statement number. Otherwise, 
the statement numbers are held in two byte 
form. Flags indicating which options are 
in use are held in the DSA. They are shown 
in appendix A. 

As the offsets may be up to 6 bytes in 
length, a device is used for statement 
numbering whereby the table is divided into 
sections that correspond to the offset 
values that are held in the first two bytes 
of the offsets. Thus offsets starting X'OO* 
are held in the first section of the table, 
offsets starting X*01* in the second, and 
so on. Each section of the table is headed 
by a pointer to the start of the following 
section,, or set to zero if there is no 
following section. The complete table is 
also headed by the value of the maximum 
offset, so that offsets beyond the program 
can be readily detected. 

The statement number is found by 
searching the correct section of the table 
for the first offset that is less than or 
equal to the last four hexadecimal digits 
of the calculated offset. 

For snap messages,, once the on-unit has 
been found and the appropriate message 
generated, the rest of the trace gives 
information about procedures, begin blocks 
and on-units. Thus all compiled code DSAs 
can be treated in the same way. 



Filename and Name of CONDITION 
Condition 



If the .error was in I/O, then the address 
of the DCLCB of the file is passed to 
IBMBERR which stores it for IBMBESN to find 
the file name. Similarly, the address of 
the control section containing the 
condition name is passed to IBMBERR if the 
CONDITION condition is raised, and IBMBESN 
puts out the required section of message. 



MESSAGE TEXT MODULES 



The message module IBMBESM calls on a 
number of message text modules to produce 
the relevant message. These modules 
consist essentially of the fixed message 
text portions of the message. The messages 
are held in groups. 

The groups are addressed from a table at 
the head of the module, and the messages in 
their turn are addressed by an offset from 
the start of each particular table in the 



message text modules. The message required 
is determined from information in the error 
code. IBMBESN puts all error messages onto 
SYSPRINT provided that SYSPRINT has net 
been declared with unsuitable attributes. 
If it has been declared with unsuitable 
attributes, then the system messages go to 
the console operator, and the snap messages 
are ignored. 



DIAGNOSTIC FILE BLOCK 



Every attempt is made to put out error 
messages on the standard print file 
SYSPRINT. However, there are no reserved 
words in PL/I and consequently the name 
"SYSPRINT" may be used for a file with 
attributes other than PRINT OUTPUT, or iray 
be used for a variable of any other data 
type. If SYSPRINT is declared as an 
unsuitable type of file it cannot be used 
for error messages and all error messages 
are written on the console. 

A control block, the diagnostic file 
block (DFB), is set up during program 
initialization to indicate whether SYSPRINT 
can be used for error messages. If 
SYSPRINT has been declared as a file the 
address of the DCLCB is placed in the DFB. 
The DFB (diagnostic file block) is 
addressed from the TCA. When an error 
message module is to be put out IBMBESM or 
IBMBPEQ inspects the DFB to see if SYSPRINT 
can be used for the message. If the flags 
in the DFB indicate that SYSPRINT cannot be 
used, the module IBMBEDO is called. 

IBMBEDO tests to see if SYSPRINT is open 
if it is not, calls IBMBOCL to open it with 
the attributes STREAM PRINT. If SYSPRINT 
has been declared as a file the address of 
the DCLCB is picked up from the DFB. 
Should the attributes STREAM and PRINT be 
incompatible with the declared or default 
attributes this is diagnosed by the OPEN 
module and Appropriate flags are set in the 
DFB to indicate that SYSPRINT cannot be 
used for error messages. This action does 
NOT raise the error condition. 

If SYSPRINT has not been declared, a 
DCLCB will be generated and SYSPRINT will 
be opened, provided that the error occurs 
before a task has been attached. If a task 
has already been attached, or if the error 
occurs in an attached task, then SYSPRINT 
cannot be opened and all error messages are 
passed to the console. 

If SYSPRINT is already open with 
unsuitable attributes this will have been 
flagged in the DFB and the messages will 
again be passed to the console. 
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If SYSPRINT has been declared as a data 
type other than a file this is flagged in 
the DFB and the error messages are set to 
the console. 

If SYSPRINT has not been declared at 
all, a diagnostic SYSPRINT is opened and 
used, provided that there is a DD card for 
SYSPRINT. 



Dump Routines 



A series of library modules are provided to 
implement the PLIDUMP facility. Module 
IBMBKDM is the dump bootstrap module which 
is part of the resident library. This loads 
and calls the transient dump control module 
IBMBKMR, which in turn links and calls 
those modules required to carry out the 
dump options specified in the call to 
PLIDUMP. several transient modules are 
used to reduce the amount of storage used 
at any one time- The organization of these 
modules is shown in figure 7.12. 

In order to ensure that as much 
information as possible is provided when a 
call to PLIDUMP is made, a special SPIE 
macro instruction is issued at the start of 
every transient routine to intercept 
program check interrupts during the 
routine, when a program check interrupt 
occurs, an attempt is made to continue with 
the dump. If the interrupt occurs in a 
program called from the dump control 
module, that particular routine is 
abandoned and a return is made to the dump 
control module. Any further routines needed 
to complete the information specified in 
the options are then called. If the 
interrupt occurs in the trace or file 
modules, the "H" option is assumed and a 
hexadecimal dump produced. If the 
interrupt occurs during the execution of 
the hexadecimal dump module, a SNAP macro 
instruction is issued by the dump control 
module and a snap dump is completed under 
the control of the supervisor. When the 
snap dump is completed control returns to 
the dump control module and the PLIDUMP is 
completed as requested in the dump options. 

As further insurance against error, the 
dump control module IBMBKMR is divided into 
sections, and, if an interrupt occurs in 
any of these sections, control is passed to 
a predefined address at the end of the 
section. Processing then continues from 
that point. 

The dump modules are fully described in 
the publication OS PL/I Transient Library 



Dumt 



In order to avoid mixing of PL/I dump and 
other information, dump data is not 
transmitted to any PL/I file. A special 
dump file known as PLIDUMP is used for the 
output of the dump modules. This file has 
its own transmitter and a special opening 
module IBMBKDO. A control block, the dump 
block, (DUB) is set up during program 
initialization and is used to hold 
information about the status of the dump 
file and to simplify access to the file. 
The DUB (dump block) is addressed from 
offset X*24» in the TCA appendage. To 
generate a PL/I dump it is necessary to 
have a DD card for PLIDUMP, or PLIDUMP. 

Before any output has been produced by 
the dump modules, the dump control module 
IBMBKMR inspects the DUB to see if the dump 
file is open. If the dump file is not 
open, and is not flagged as unopenable, the 
control module calls the dump file open 
routine (IBMBKDO) to open the file. 
IBMBKDO acquires space for the necessary 
control blocks loads the dump transmitter 
and attempts to open the dump file. 

If the attempt to open the dump file 
fails, IBMBKDO flags the DUB and returns. 
The DUB flags are tested by IBMBKMR, and, 
if the file has not opened, a message is 
put out and the dump is terminated. The job 
is either continued, 

terminated or an exit is made from the 
task, according to the options in the dump 
parameter. IBMBKDO uses either the 
declared PLITABS or loads the system 
default PLITABS module, IBMBSTAB to 
determine the pagesize for PLIDUMP output. 
Provided a pagesize of two or more is 
specified, the pagesize in PLITABS will be 
used. 



If the dump file can be successfully 
opened, IBMBKDO tests the attributes of the 
file. It it appears from the attributes 
that the dump is being transmitted directly 
to a printer or terminal, , the transmitter 
IBMBKDT is loaded. If it appears that it is 
being transmitted to a direct- access device 
or tape unit, the transmitter IBMBKDB is 
loaded. 

If IBMBKDT is loaded, two buffers are 
acquired. The address of one of these 
buffers is placed in the DUB. During the 
execution of the dump, the dump data is 
generated in the buffer which is addressed 
by the DUB. When the first buffer is full, 
a call is made to the transmitter module to 
transmit the buffer to the dump file. A 
test is then made to see whether the second 
buffer has completed the previous I/O 
operation. When the previous I/O operation 
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(if any) is complete the address of the 
second buffer is placed in the DUB and the 
operation continues. If IBMBKDB is loaded, 
only one buffer is used. 

When the dump is finished, the dump file 
remains open and the transmitter is 
retained. This speeds execution of further 
dumps, rhe storage is freed and the dump 
file closed by IBMBPIT when the program is 
terminated. The dump file is not placed on 
the open file chain. IBMBPIT tests the DUB 
to see if the file is open. 



overwriting is detected, the error handler 
is called with a code indicating the error 
condition. 

The message put out by IBMBPEV where 
possible contains the number of the PL/I 
statement being executed when an ABEND 
occurred. 



Miscellaneous Error Modules 



A numbea: of further library modules are 
used in certain exceptional error 
situations. These fall into two groups. 

1. ABEND analyzers 

IBMBPES Determine action to be taken. 

IBMBPEV Put out message if necessary, 
and dump if possible. 

2 . Exceptional error me ss age modules 

IBMBPEP Exceptional error message 
director 

IBMBPEQ No main procedure or more 

than 1021* files and controlled 
variables. 

IBMBPER No main storage available 

IBMBPET Interrupt in error handling 
routines or abnormal task 
termination 

All these modules are transient library 
modules. They are fully described in the 
relevant program logic manual. 



EXCEPTIONAL ERROR MESSAGE MODULES 



The exceptional error message modules 
consists of a director and three message 
modules. This arrangement has been adopted 
so that the minimum space will be used. It 
is necessary to conserve space as lack of 
space is one of the reasons for calling the 
modules . 

The director module IBMBPEP determines 
the nature of the exceptional error and 
calls the necessary module to put out the 
message. 

The table below shows the circumstances 
in which IBMBPEP is called and message 
modules then called by IBMBPEP. 



Circumstance 

Insufficient main 
storage to set up 
program management area 

No main procedure 



Too many files or 
controlled variables to 
be held in PRV 



Calling 
module 

IBMBPII 



Code in 

dummy 

PLIMAIN 

IBMBPII 



IBMBPEP 
calls 

IBMBPER 



IBMBPEQ 



IBMBPEQ 



The ABEND analyzer IBMBPES is entered 
during an ABEND because it was nominated in 
the STAE macro instruction issued during 
program initialization. 

The ABEND is analyzed by checking the 
major blocks to see if they have been 
overwritten. If the backchain of DSAs has 
become overwritten, the ABEND is allowed to 
continue under supervisor control. If the 
DSA backchain is correct but critical 
control blocks appear to be overwritten, 
IBMBPEV is called to put out a message and 
if possible to provide a PLIDUMP. If no 



Interrupt in error 
handling routine 

Abnormal termination 
of task 



IBMBERR IBMBPET 
entry point C 



IBMTPIR 



IBMBPET 



Module IBMBPEQ puts out the the message to 
SYSPRINT except in those circumstances 
where SYSPRINT cannot be used. (See above 
under "Error Message Modules"). IBMBPET 
and IBMBPER always put out their messages 
on the console as they are called in 
circumstances where SYSPRINT is likely to 
fail or where operator, rather than 
programmer action, is required. 
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PL/ I PROCEDURE TO BE COUNTED 

1 COUNTIT:PROC OPTIONS (MAIN) ; 

2 DO 1=1 to 2; 

3 PUT LIST (I) ; 

4 END; 

5 END COUNTIT; 

In this procedure, the do- loop in statements 2 through 4 will be 

executed twice, and the other statements once. Statement 2 will be executed 

three times as a return is made at the end of the loop to test the value 

of I. Note: This code may compile in different ways. See section on 

DO- loops in chapter 2. 



HISTORY OF THE STATEMENT FREQUENCY COUNT TABLE 

After the branch-in to statement number 1 , the table is set up with a value 
of 1 for the first statement and for all others, thus: 

statement number 12 3 4 5 
branch count 10 

After the branch-out at statement 4 , the count of the next statement 
is decremented by one and the table becomes: 

statement number 12 3 4 5 
branch count 1 -1 

After the branch- in at statement 2, the branch count for statement 2 is 
incremented by one and the table becomes: 



statement number 
branch count 



5 
-1 



At Statement 4 , a further branch out is made and a return made to 

statement 2 to test the value of I. One is subtracted from the value 

of statement five making the count -2 and one added to the count 

of statement 2 making it 3. Because I is greater than 2 a 

branch is made after the test to statement 5. This results in one 

being subtracted from the count for statement 3 and one being added to 

the count for statement 5. At the end of the program the table reads: 



statement number 
branch count 



3 
-1 



5 
-1 



ANALYSIS OF THE STATEMENT FREQUENCY COUNT TABLE 

A value known as the current count , which is initially set to zero, 
is added to the branch count for each statement in turn. The sum is 
the number of times the statement was executed; this value also becomes 
the current count. 



statement number 


current 


count 


branch count 


times executed 


1 







1 


0+1= 1 


2 


1 




1 


2+1= 3 
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2 







3-1= 2 


4 


2 







2+0= 2 


5 


2 




-1 


2-1= 1 



Figure 7.13 



How branch counts are used to calculate the number of times each 
statement is executed. 



Chapter 7: Error and Condition Handling 113 



The FLOW and COUNT Options 



The FLOW and COUNT options are used to 
provide information about which statements 
are executed in a particular run of a 
program. The FLOW option is used to 
maintain a trace of the most recently 
executed statements. The COUNT option is 
used to maintain a count of the number of 
times each statement is executed. 

Both options are implemented by calling 
an interpretive library routine, IBMBEFL, 
at every point in a program where the flow 
of control may not be sequential. The 
library routine, IBMBEFL, analyzes the 
situation and updates taiales to retain a 
record of the branches made. IBMBEFL is 
also called during program initialization 
to set up housekeeping information. Two 
transient library modules are used to 
interpret the tables set up by IBMBEFL and 
to put out the information. The routines 
are IBMBESN for the FLOW option, and 
IBMBEFC for the COUNT option. 

The compiler generates the same 
executable code for both the COUNT and the 
FLOW option. Consequently, if either 
option is specified for compilation, either 
or both can be made available at execution 
time. If neither is required during 
execution but one or other was specified 
for compilation, the code to call IBMBEFL 
is stili executed and IBMBEFL still forms 
part of the load module. When IBMBEFL is 
called in this situation, it returns 
control to compiled code without recording 
any information. 

Points at which the flow of control may 
not be sequential are known as branch- in 
and branch-out points. For example, 
labeled statements and entry points are 
branch-in points, and GOTO statements are 
branch-out points. At branch-in and branch- 
out points the compiler places code that 
will call IBMBEFL. If the branches are 
taken, they are recorded. For COUNT they 
are recorded in a table known as the 
statement freguency count table. For FLOW, 
they are recorded in a table known as the 
flow statement table. 

yse_9f Brianching Information for FLOW 

For the FLOW option, a list of the 
statement numbers at which branches were 
taken and a list of any changes of 
procedure is retained. 

FLOW output consists simply of the list 
that is recorded by IBMBEFL and typically 
takes the form shown below. 

12 TO 18 

27 TO 35 IN SORTER 



76 TO 108 IN TESTER 
13U TO 77 IN SORTER 

This indicates that the program branched 
from statement 12 to statement 18, then ran 
sequentially from 18 to 27. After 
statement 27 it branched to, or called, 
statement 35 in the procedure called 
SORTER. Control then ran sequentially to 
statement number 76, at which point it 
passed to statement number 108 in the 
procedure called TESTER. Control then ran 
sequentially from 108 to 134 and finally 
passed to statement 77 in SORTER. 

Use of Branching Information for^COUNT The 
COUNT option calculates the number of times 
each statement is executed by recording 
branch- in and branch-out points as they 
occur and analyzing them at the end of the 
program. 

The formula used for calculating the 
number of times each statement is executed 
from the branch count is: 

Cn=Cn-l+BIn-BOn-l 

Where: 

Cn =the number of times the statement 

was executed. 
Cn-1 =the number of times the previous 

statement was executed. 
Bin =the number of times the statement 

was branched to. 
BOn-l=the number of times the previous 

statement was branched from. 

TO retain the information, a count field 
is set up for every statement in the 
program, and branches-in and branches-out 
are recorded when they occur. Every time a 
branch-in is made, the count for the 
statement to which the branch is made is 
incremented by one. Every time a branch-out 
is made, the count for the statement after 
the branch-out is decremented by one. When 
the program ends, statements that have 
values other than zero mark the beginning 
and end of ranges of statements that have 
been executed the same number of times. 
The number of times the ranges of 
statements have been executed is calculated 
by adding the value in the count field to 
the sum of any preceding values. 

This process can be followed in figure 
7.13. 

Special cases There are a number of special 
cases that require additional action, 
either by the compiler, or by IBMBEFL, or 
by both. These special cases arise for 
three reasons: 

1. Branches can be caused by 

interrupts, but the points at 
which they will occur cannot be 
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predicted during compilation. 
Consequently the compiler cannot 
place calls to IBMBEFL at these 
points. 

2. Branches to labeled statements, 
can come from either the same 
block or a different block. 
Consequently the code generated by 
the compiler cannot be used to 
indicate whether a new block entry 
is required. 

3. The algorithm used for the COUNT 
option is not effective for CALL 
statements and function references 
because the branch-in and branch- 
out are made to and from the same 
statement. 

The first case is handled by IBMBEFL 
checking for the occurrence of an interrupt 
when it is called in situations where one 
could have occurred. The second case is 
handled by altering the GOTO code in the 
TCA so that it calls IBMBEFL to set 
appropriate flags when a GOTO out of block 
occurs. A test for the flags is made when 
the call to IBMBEFL for the branch-in at 
the labeled statement is made. The third 
case is predictable during compilation and 
is handled by the compiler setting up 
different code for branches-in to CALL 
statements and function references, and by 
IBMBEFL testing for such code. Details of 
the methods used are given later. 



IMPLEMENTATION OF FLOW AND COUNT 



Tables Used 



FLOW and COUNT 



To enable it to retain FLOW and COUNT 
information, IBMBEFL sets up tables in 
dynamic storage. Figure 7.14 shows their 
contents. Details of their formats are 
shown in appendix A. -43 

EI;2W_0Et ion : FLOW information is retained 
in a table called the flow statement table. 
The flow statement table has three 
sections; a header section containing 
housekeeping information, a statement 
number section holding the numbers of 
statements that were branched to or from 
plus flags to indicate the type of entry, 
and a procedure names section containing 
the names of procedures and on-units to 
which branches are made. The length of the 
flow statement table is determined by the 
values given to "n" and "m" when the FLOW 
option is specified. 

When all the spaces in the table for 



statement numbers or procedure names have 
been filled, the earliest entries are 
overwritten. The fields in the header 
section are used to indicate which is the 
next space available in the table. 

The table is set up during program 
initialization and is addressed from the 
TCA. 

C0yNT_0pt i on : COUNT information is retained 
in tables called statement frequency count 
tabl eg . The tables have a field for every 
statement. They are set up when an 
external procedure is entered. A table is 
needed for every external procedure because 
two external procedures can contain the 
same statement numbers. 

Statement frequency count tables are 
chained together and addressed from the TCA 
appendage (the TIA) . Two addresses are 
kept in the TIA, the address of the current 
statement frequency count table (that is 
the table that was last used) and the 
address of the statement frequency count 
table for the first procedure in the chain. 
Statement frequency count tables are 
associated with their matching external 
procedures by having the address of the 
static control section for the procedure 
placed at a fixed offset in the table. (A 
static control section is unique to an 
external procedure and its address can be 
easily accessed as it is addressed 
throughout compiled code by register 
three) . The last statement frequency count 
table in the chain has its chaining field 
set to zero. 

The length of statement frequency count 
tables depends on whether the GOSTMT or 
GONUMBER option is in effect. For GOSTMT 
one fullword is used for each statement in 
the procedure. For GONUMBER, two fullwords 
are used. This is because for GONUMBER it 
is necessary to retain the statement number 
as well as the count value. (For GOSTMT, 
the numbers will start at one and be 
incremented by one, and no record need 
therefore be kept.) If neither GOSTMT nor 
GONUMBER is in effect, no attempt is made 
to count the statements executed in the 
procedure and a statement frequency count 
table is not set up. 



Executable. Code for FLOW and COUNT 

As described in the introduction, there are 
four stages in the implementation of the 
FLOW and COUNT options. These are: 

1. Action diaring compilation. The 
code to call the interpretive 
library routing IBMBEFL 
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FLOW STATEMENT TABLE 
One table for the program 



STATEMENT FREQUENCY COUNT TABLES 
One table for each external procedure 



HEADER 
SECTION 



STATEMENT 

NUMBER 

SECTION 



PROCEDURE 

NAMES 

SECTION 



Contains: 

• Pointers to next entry in each 
section of the table. 

• Other housekeeping data. 



Contains: 

• Statement numbers of branches 
plus flags indicating type of 
entry. 



Contains: 



Names of procedures and types 
of on-units that have been 
branched to. 



HEADER 
SECTION -< 



BRANCH 
COUNT ^ 
SECTION 



Contains: 

• Pointer to any further tables. 

• Address of static control section of 
associated external procedure. 

• Other housekeeping data. 



Contains: 



A field for each statement in the 
program containing a count which 
Is Incremented when the statement 
is branched to and decremented when 
the statement Is branched from. 



i Figure 7.1t». The contents of the flow statement table and the statement 
j frequency count table. 
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is placed at every predictable 
branch-in and branch-out point. 

2. Action during program 
initialization. The necessary 
housekeeping fields are set up. 
This is done by the program 
initialization module IBMBPII and 
the flow module IBMBEFL called at 
entry point A. 

3. Action during execution. The 
branch- in and branch-out 
information is collected by 
IBMBEFL, called at entry point B. 
IBMBEFL is also called at entry 
point C to handle certain special 
cases. The call is made when the 
GOTO out-of- block code is 
executed. 

4. Action during output. The 
necessary information is written 
out. This is done by IBMBESN for 
the FLOW option and IBMBEFCA for 
the COUNT option. 

These four stages are described in detail 
in the following sections. 

Action During cgmpilation 

During compilation, the compiler examines 
the program and generates suitable code at 
each predictable branch-in and branch-out 
point. Predictable branch- in points are: 

• entry names 

• labeled statements 

• THEN and ELSE clauses of IF 
statements. 

• entries to on-units 

• returns from CALL statements or 
function references. 

• the statement following the 
END statement of an internal 
procedure. 

Predictable branch-out points are: 



GOTO statements 

function references 

CALL statements 

IF statements 

RETURN statements 

END statements 

the statement before the 

PROCEDURE statement 

of an internal procedure. 



The code for branch-out points is so placed 
that the call to IBMBEFL will not be made 
unless the branch is taken. 



Statements preceding and following 
internal procedures are treated as branch- 



out and branch-in points because the 
statement numbers of the statements 
executed are not sequential although the 
actual flow of control is sequential. If 
this were not done, the method used for 
counting statements would not work because 
the statements in the internal procedure 
would be given the count values of the 
preceding statements. 

The code placed at the branch-in and 
branch-out points takes the following form: 



L 15, 84(0,12) 

BALR lU, 15 
DC X'80O4* 



Pick up address of 
IBMBEFL from TCA. 

Branch to IBMBEFL. 

Constant containing 
a two-bit flag 
remainder for 
statement number. 



Register 14 is set to the constant 
containing the statement number and flags 
by the BALR instruction. IBMBEFL can 
therefore pick up the statement number by 
examining the constant. 

The constant is a halfword if the STMT 
option was used and a fullword if the 
NUMBER option was used. In both cases, the 
first two bits are used as flags and the 
remainder is used for the statement number. 

The flags indicate: 

• branch-in 

• branch-out 

• branch-in to a new procedure 

or on-unit. 

• return to point of interrupt 
from end of on-unit. 



For a branch-in to a CALL statement or a 
function reference, which takes place when 
the return is made, BAL 14, 0(15) is 
generated instead of BALR 14, 15. This 
situation requires to be recognized because 
the branch-in and branch-out both occur 
from the same statement. If it were not 
treated as a special case, the count of the 
next statement would be decremented by one 
when the branch-out was made and the count 
for the CALL statement would be incremented 
by one on return. Thus the CALL statement 
would apparently have been executed twice. 
The increment is therefore added to the 
statement after the CALL statement, thereby 
giving the correct values. 

In addition to the calls to IBMBEFL, the 
compiler also generates control sections 
that will result in IBMBEFL being link- 
edited and subsequently called during 
program initialization to set up the 
necessary housekeeping machinery to handle 
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COUNT or FLOW. 

For the FLOW option, the compiler 
generates a control section called PLIFLOW 
that can be used during program 
initialization to call IBMBEFL. This 
control section takes the following form: 



USING 


♦ ,15 


L 


15,VC0N 


BALR 


1,15 


DC 


H'n' 


DC 


H*m' 


DC 


V(IBMBEFLA) 



VCON 



For the COUNT option, the compiler 
generates a control section called PLICOUNT 
that can be used to call IBMBEFL to 
initialize the COUNT option. It is the 
same as PLIFLOW except that the halfwords 
'n' and 'ir' are replaced by a fullword 
X'80000000'. 

The calls to IBMBEFL are generated if 
either FLOW or COUNT is defined at compile- 
time. The control sections are generated 
if the corresponding option is specified at 
compile time. 



Action During, Program_Initializat 



During program initialization, the program 
initialization module IBMBPII determines if 
either FLOW or COUNT or both are required. 
If the user specified either FLOW or COUNT 
during compilation, the requested option 
will be in effect during execution unless 
specifically overridden by the NOFLOW or 
NOCOUNT execution time option. If he 
specified either option for compilation he 
can also specify the other for execution. 

To determine which options are to be used, 
IBMBPII inspects the execution time options 
and checks for the presence of PLIFLOW or 
PLICOUNT which will indicate that the 
corresponding option was requested at 
compile-time. 

If one or both of the options are requested 
for execution but neither was requested for 
compilation, IBMBPII generates a message to 
say that the option will not be available. 

If an option is specified for compilation 
and not overridden for execution time, the 
corresponding control section will be 
available and IBMBPII passes control to 
IBMBEFL at entry point A through the code 
in the control section. If the control 
section corresponding to the required 
option does not exist, IBMBPII calls 
IBMBEFLA directly, passing it a value in 
register 0. This value is 4 if FLOW is 
required and 8 if COUNT is required. 



If one or both of the options have been 
requested during compilation but neither 
are required during execution, IBMBPlI sets 
FLOW values of (0,0) and calls IBMBEFLB to 
initialize the FLOW option. In this 
situation, IBMBEFL sets the address of the 
flow statement table and the addresses of 
the statement frequency count tables to 
zero. 

To initialize FLOW, IBMBEFLA sets up the 
flow statement table and initializes it 
with a dummy statement number entry and a 
dummy procedure name entry. The address of 
the flow statement table is placed in the 
TCA. If FLOW is not required, or if 
FLOW(0,0) has been specified, the address 
is set to zero. 

To initialize COUNT, two addresses in 
the TIA are initialized. The first, which 
will contain the address of the first of 
the chain of statement frequency count 
tables, is set to zero. The second which 
will contain the address of the current 
statement frequency count table is set to 
point to the first. If COUNT is not 
required, both fields are set to zero. 

For both FLOW and COUNT, the address of 
entry point B of IBMBEFL is placed in the 
TCA; the GOTO code, which is in the TCA, is 
altered so that it calls IBMBEFL at entry 
point C. (This is necessary so that changes 
of block caused by GOTO statements can be 
intercepted and flagged.) 



Action During Execution 

During execution, calls from compiled code 
at branch-in and branch-out points are made 
to entry point B of IBMBEFL whose address 
has been placed in the TCA. The action 
then taken depends on which options are in 
effect, the type of the previous entry, and 
the type of the present entry. 

Calls are also made to IBMBEFL at entry 
point C when the GOTO code in the TCA is 
executed. 

IBMBEFL When Called at Branch-In and 

Branch-Out~_Points ~ 

When IBMBEFL is called at branch-in or 
branch-out points, the call goes to entry 
point B whose address has been placed in 
the TCA during program initialization. 
IBMBEFL first checks* to see which, if 
either, of the options is required by 
testing the fields used to address the flow 
statement table and the current stateirent 
frequency count table. If either of these 
is set to zero, the correpsonding option is 
not in effect. If both are set to zero, 
control is returned to compiled code. 
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If one or other of the options is in 
effect, there are four possible cases that 
require different action: 



1. A branch-in following a 
branch-out or vice versa. 

2. A branch-in following another 
branch-in 

3. A branch-in to a new block. 

4. Return from an on-unit to the 
point of interrupt. 

These cases are dealt with individually in 
the sections that follow. 

C ase 1 . Branch-In Following a Branch-Out 

or Vice Versa This situation indicates 
non-sequential flow of control, and must 
therefore be recorded in the FLOW and COUNT 
tables. For FLOW, the new statement number 
together with flags indicating a branch-in, 
a branch- out, or a branch- in to a procedure 
or on-unit, are entered in the position 
indicated by the pointer at the head of the 
flow statement table. The pointer is then 
updated to point to the next available 
space. If the next space would be outside 
the table, the pointer is reset to the head 
of the statement number section of the 
table. 



For COUNT, the count value in the field 
for the appropriate statement number is 
altered. For a branch-in, the count of the 
statement branched to is incremented by 
one. For a branch-out, the count of the 
statement after the statement branched from 
is decremented "by one. 

If IBMEEFL is being called for a branch 
in, it is possible that it was caused by a 
GOTO-out-of-block and a new procedure or 
on-unit name may need to be recorded. In 
this situation, IBMEEFLC will have been 
called during the execution of the GOTO- 
out-of-block code and will have set a flag 
in the flow statement table. The flag is 
therefore tested and, if it is found on, 
the entry is treated as an entry to a new 
block. See case 3. 

A further possibility is that the branch- in 
will be a return to a CALL statement or a 
function reference. These are 
distinguishable because the call to IBMBEFL 
is made by a EAL instruction rather than a 
BALR instruction. If the COUNT option is in 
effect, this must be tested for, and the 
count value of the next statement rather 
than the current statement be incremented 
This is necessary because the branch-out 
and the branch-in for CALL statements and 
function references are both made at the 
same statement, (see description under 



"Action during Compilation" earlier) . 



Case_2i A Branch-in Followed_by Another 

Branch- inj__ No action need be taken as such 
a situation can only be caused by 
sequential flow. For example consider the 
statements: 



LABI: 
LAB2: 



X=Y; 
Z=X; 



Both LABI and LAB2 are potential branch-in 
points, but, if a call to IBMBEFL is made 
for LAB2 immediately after a call has been 
made for LABI, it is plain that the flow of 
control has been sequential. Consequently 
when a branch-in follows another branch-in, 
IBMBEFL returns control to compiled code 
without taking any action. 

This situation does not arise with 
branch-out points, because the code to call 
IBMBEFL is only executed if the branch is 
taken. 

Case_3^ .A_Branch-I n_to_a_N ew_Block£ This 

case requires that block information be 
entered for the FLOW option, and that, for 
the COUNT option, a check be made to see 
whether a new external procedure has been 
entered. If it has, a different statement 
frequency count table will have to be used 
because there is one for each external 
procedure. 

Special action will be required if the 
block entered is an on-unit. This is 
because the branch-out will have been made 
at the point of interrupt and this will not 
have been automatically recorded by a call 
to IBMBEFL. When a new block is entered a 
test is therefore made on the DSA flags of 
the block to establish whether it is an on- 
unit. The action taken if it is a on-unit 
is described later under the heading 
"Branch-In to an On-Unit. " 

After any action required to handle 
entry into an on-unit, the following will 
take place. 

For FLOW, the name of the block roust be 
discovered and placed in the next available 
space in the names section of the flow 
statement table. Also, the statement 
number entry must be flagged to show that 
it marks a change of block. The procedure 
name is found following the DSA chain back 
until a procedure DSA is found and 
accessing the name, which is held at a 
standard offset from the entry point of the 
procedure. When the procedure name has 
been found, the statement number and flags, 
and the procedure name, are placed in the 
appropriate sections of the flow statement 
table and the pointers altered to point to 
the next available fields. 



Chapter 7: Error and Condition Handling 119 



For COUNT, a check irust be made to discover 
whether a new statement frequency count 
table is required. This is done by 
comparing the address in the register 3 
save area of the DSA of of the procedure 
that called lEMBEFL with that at offset 
X'4* in the current statement frequency 
count table. If they are the same no action 
is required, because the new block must 
have the same static control section as the 
previous block and consequently must be in 
the same external procedure. If the 
addresses are not the same, a search is 
made down the chain of statement frequency 
count tables for a matching table. If one 
is found, the address of the current table 
is set to point to the table that has been 
found, and the required entry made in that 
table. If no matching table is found, a new 
table must be set up. 

Creating a New Statement Frequency Count 
Table ; Before creating a new statement 
frequency count table, IBMBEFL checks to 
see if a statement number table exists for 
the new procedure. If it does not, 
counting will not take place. In this 
situation, the current statement frequency 
count table is flagged to indicate that 
counting is to be suspended until another 
procedure is entered, and control is 
returned to compiled code. 

Provided a statement number table does 
exist, a new statement frequency count 
table will be required. IBMBEFL first 
obtains the required amount of non-LIFO 
storage for the table. One fullword is 
required for every statement in the 
external procedure if it was compiled with 
the GOSTMT option, and two fullwords are 
required for every statement if it was 
compiled with the GONUMBER option. The 
count fields are set to zero, and, for 
procedures compiled with the GONUMBER 
option the numbers are inserted in the 
tables. The new table is then linked with 
its matching external procedure by placing 
the address of the static control section 
for the procedure in the new table. 

Branch-intg an On-unit; If the code that 
called IBMBEFL is found to be in an on- 
unit, special action is required. The 
statement number for the point of interrupt 
must be discovered and appropriate entries 
made in the flow and count tables, before 
the data for the entry to the on-unit can 
be recorded. This is because there will 
have been no call to IBMBEFL at the point 
of interrupt to register a branch-out. The 
statement number of the interrupt is found 
by IBMBEFL in the same way as that used by 
the error message modules, described 
earlier in this chapter. When the number 
has been found, it is incorporated in the 
flow and count tables as if it were a 
normal branch-out. The branch- in entry is 



then handled as if it were a normal entry 
to a new block. It is possible for the FLOW 
option to be in effect without there being 
a statement number table available. In 
this situation, a statement number of zero 
is entered in the flow statement table for 
the branch-out at the point of interrupt. 

A problem also exists for COUNT if an 
interrupt results in the termination of a 
program. In this situation, the interrupt 
point must be marked as a branch/out, 
otherwise, statements after the interrupt 
would have an incorrect count value. This 
situation is checked for when the FINISH 
condition is raised. During the handling 
of the FINISH condition, the GOTO code is 
executed and IBMBEFL is called at entry 
point C. A check is then made to see if 
FINISH was raised because of an interrupt. 
If it was, the point of interrupt is 
discovered and entered as a branch-out 
point in the appropriate statement 
frequency count table.. 

Case_4^ S6turn_from_jOn^imit_to_Point_of 

Interrupt ; When return is made from the 
end of an on-unit to the statement that 
caused the interrupt, there will be nc 
automatic call (resulting from code 
inserted during compilation) to IBMBEFL. 
The necessary information for the flow and 
statement frequency count tables is 
therefore entered when IBMBEFL is called at 
the end of the on-unit. The statement 
numbers passed for such calls are specially 
flagged so that IBMBEFL discovers the point 
of interrupt and takes the necessary action 
to update the flow statement table and 
statement frequency count tableis. 



_Action_on_Out£Ut 



Interpreting the FlQW_gtatement.„ Table 

Information from the flow statement 
table is interpreted by the message module 
IBMBESN or the PLIDUMP routines, and 
transmitted in the form of statement number 
pairs which are associated with the names 
of procedures or with on-unit condition 
types. 

To extract the information, the message 
module must. know from which points output 
in the statement number and procedure names 
section of the table output is to start. 
It must also be able to match the entries 
in the two sections of the table. 

The starting points in both sections of 
the table are found by checking whether the 
dummy entry, inserted during program 
initialization, has been overwritten. If 
the dummy entry has not been overwritten. 
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the starting point is the first entry in 
that section of the table. If the durtiniy 
entry has been overwritten, the starting 
point will be the entry flagged as the next 
available entry. This is because the table 
is used cyclically, with the newest entry 
overwriting the oldest entry. 

Statement numbers are matched with 
procedure names by comparing the number of 
procedure names with the number of 
statement number entries that are flagged 
as being associated with procedure name 
entries. If the two numbers are the same, 
the first procedure name will be associated 
with the first statement number that 
requires a procedure name. If there are 
more procedure names than statement numbers 
that require procedure names, the trace of 
procedures must be longer than the trace of 
statement numbers. Accordingly, the 
procedure names are put out without 
statement numbers until the point is 
reached where the number of procedure names 
left is the same as the number of statement 
numbers that require them. From that point 
on statement numbers and procedure names 
are put out together. If there are more 
statement numbers that require procedure 
names than there are procedure names, the 
trace of statement numbers must be longer 
than the trace of procedure names. The 
earliest statement numbers are put out 
without names and, where a procedure name 
is required, "UNKNOWN" is used. When the 
number of names required matches the number 
available, the procedure names are put out 
with the statement numbers. 



ISt§£E£®till3 the statement frequency count 
tables 

Module IBMBEFCA is called at program 



termination to print count information. 
Output is tabular and printed three columns 
to a page. An entire page is built before 
transmission. 

Output for a procedure begins with the 
procedure name. This is followed by the 
column headings: "FROM TO COUNT". The 
current count is initialized to zero and 
the first non-zero entry in the table is 
found. The associated statement number is 
then placed in the •FROM* part of a 
temporary line and the value for the non- 
zero entry is added to the current count. 
The entries for the following statements 
are scanned until one with a non-zero count 
value is found. The number of the 
preceding statement is then placed in the 
'TO' part of the line and the current count 
in the 'COUNT' part. This line is included 
in the page. The statement number found is 
then placed in the 'FROM* part of the 
temporary line and its branch count (which 
may be negative) is added to the current 
count. The scan of entries continues until 
another non-zero count is reached, and the 
process is repeated. 

If the count for a range is zero, the 
line is not moved into the page but the two 
statement numbers are saved for separate 
printing. Whenever a line is moved into 
the page, checks are made for the end of a 
column and the end of the page. When the 
page is full it is transmitted. 

The process is continued until the end of 
the table is reached. 

The next table is then processed, until all 
procedures have been handled. 

Finally, ranges of unexecuted statements 
are printed for each procedure. 
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COMPILATION 



c> 



Ensure program 
tests for all enabled 
non-system-detected 
interrupts and calls 
error handler when 
they occur 



Compile on-unitsas 
separate program 
blocks 



3 



INITIALIZATION 



Issue SPIE&STAE 
macros to pass 
system detected 
interrupts to 
error handler 



> 



PROLOGUE CODE 



PROCEDURE CODE 



:> 



Set up flags to 
indicate to error 
handler which 
conditions are 
enabled 



Mainline code 



:> 



Execute ON 
statement by setting 
flag indicating on- 
unit is established 



Mainline code 



•> 



PROCEDURE CODE 



C> 



Instruction capable 
of causing condi- 
tion not detectable 
by system 




/^ Test ^\^^_^^ ^^^ 

hether conditi ^^ Mainline code / 
^occurred^.-'j^l^T v 



OBJECT PROGRAM 



Prepare data 
including condition 
type and built in 
function values 



Call error handling 
module IBMBERR 




Mainline code 



> 



Determine PL/I 
condition from 
PSW 



IBMBERR 

Error handling module 

ENTRY POINT.A 



ENTRY POINT B 



IBMBERR 

Error handling module 



Return to point 
of interrupt 



YES 



If no GOTO out 
of on-unit take 
action for normal 
return. 
(See below) 



Execute action 
specified in on unit 



YES 




Call message 
module to put 
out message 



Take standard 
system action 
(See below) 



Possibly put out message, then take one of actions shown 
below depending on condition that occurred 



Return to point 
of interrupt 



Call IBMBPIR to 
terminate program 
or task 



Raise further 
condition 



Figure 7.15. Outline of error handling 
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Set up control blocks 
from file declaration 
and I/O statements 



COMPILER 



Call PL/I library or data 
management routines 
passing control blocks 



COMPILED CODE 



"111,, 



'i!ilk. 



OPEN & CLOSE STATEMENTS TRANSMISSION STATEMENTS 



■•'«,! 



i|'li„. 



In-line I/O Library call I/O 



"'|iii||., 



Wh, 



PL/I LIBRARIES 



OPEN/CLOSE BOOTSTRAP 
ROUTINE 

(Resident library) 



TRANSMITTER INTERFACE 
ROUTINE 

(Resident library) 



"•,'8,i\, 



"%> 



OPEN ROUTINES 



(Transient library) 



CLOSE ROUTINE 



(Transient library) 



PL/I TRANSMITTER 



(Transient library) 



V-3 






DATA MANAGEMENT 
ROUTINES 



OPEN 
ROUTINE 



CLOSE 
ROUTINE 



TRANSMITTER ROUTINE 



Figure 8.1. The principles used in record I/O implementation 
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Chapter 8: Record-oriented Input/Output 



Introduction 



Summary of Record I/O Implementation 



This chapter considers the implementation 
of the following statements: 

File declarations 

Open and close statements 

READ, WRITE, DELETE, LOCATE, UNLOCK, 

and REWRITE statements referred to 

generically as transmission statements 

Together, these statements make up record 
I/O. 



File Declarations 



For a file declaration, the compiler 
generates two control blocks: the declare 
control block (DCLCB) and the environment 
control block (ENVB) . Together, these two 
control blocks contain a complete record of 
the file declaration. 



The OS PL/I Optimizing Compiler uses the 
data management routines of OS/360 to 
implement record I/O. These routines offer 
facilities similar but not identical to 
those of the PL/I language. The data 
management routines require that: 

1. A data control block CDCB) is set up 
to describe and identify the data set. 

2. OPEN and CLOSE macro instructions are 
issued to open and close the data set. 

3. GET, PUT, READ, or WRITE macro 
instructions are normally issued to 
store or obtain a new record. 

The data management routines transmit the 
data one block at a time between the data 
management buffer and the external medium, 
but each separate macro instruction issued 
by the program results in only a single 
record being passed. When a transmission 
error occurs, or when the end-of-file is 
reached, the data management routines 
either set flags indicating the error or 
branch to error-handling or end-of-file 
routines that can be specified by the 
programmer. 

The basic method used by the optimizing 
compiler to implement record I/O is to 
retain the source program information in a 
number of control blocks, and to pass these 
control blocks to PL/I library routines 
which interpret the information and carry 
out the necessary action by calling data 
management routines in the appropriate 
manner. The method is summarized below, and 
shown diagramatically in figure 8.1. 
Figure 8.15 shows the overall scheme in 
greater detail. 



OPEN Statements 



OPEN statements are compiled as a call to a 
resident-library bootstrap routine, 
IBMBOCL, which has passed to it an open 
control block (OCB) containing the 
attributes and environment options that 
have been used in the OPEN statement. 

The bootstrap routine loads and calls a 
number of transient routines that build a 
definitive control block, known as the file 
control block (FCB) , from information in 
the DCLCB, ENVB, and OCB. The file is 
associated with the data set, and the 
appropriate PL/I transmitter module is 
loaded. 

The FCB is used during the execution of 
transmission statements to access all file 
information. It is addressed via the DCLCB 
and the pseudo-register vector. 



Transmission Statements 



For the majority of file and statement 
types, details of statement type, of 
record, key, and event variables are set up 
in control blocks during compilation; 
during execution, these control blocks are 
passed to a resident-library interface 
routine, IBMBRIO. IBMBRIO then calls a PL/I 
transient-library transmitter module, which 
issues the appropriate data management 
macro instruction, and checks for errors, 
before returning control to compiled code. 
This method is known as library-call I/O. 
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RESIDENT LIBRARY 

IBMBOCL Open/Close bootstrap routine 
IBMBRIO Record I/O interface routine 

TRANSIENT_LIBRARY 

Open_Modules 

IBMBOPA Open error handler 

IBMBOPB Open routine Phase I 

IBMBOPC Open routine Phase II 

IBMBOPD Open routine phase III 

IBMBOPE Open routine phase II (VSAM) 

IBMBOPZ Direct output file formatter 

Qlose_Module 

IBMBOCA Close module 

^J^^gjOsigit^ter^Modules 

IBMBRAA Regional sequential output 
IBMBRAB Regional sequential output 
IBMBRAC Regional sequential output 
IBMBRAD Regional sequential output 
IBMBRAE Regional sequential output 
IBMBRAF Regional sequential output 
IBMBRAG Regional sequential output 
IBMBRAH Regional sequential output 
IBMBRAI Regional sequential output 
IBMBRBA Regional sequential 

input/update 
IBMBRBB Regional sequential 

input/update 
IBMBRBC Regional sequential 

input/update 
IBMBRBD Regional sequential 

input/update 
IBMBRBE Regional sequential 

input/update 
IBMBRBF Regional sequential 

input/update 
IBMBRBG Regional sequential 

input/update 
IBMBRCA Unbuffered consecutive 
IBMBRCB Unbuffered consecutive 
IBMBRCC Unbuffered consecutive 
IBMBRCD Unbuffered consecutive OMR 
IBMBRCE Unbuffered consecutive 

associated file 
IBMBRDA Regional direct non-exclusive 
IBMBRDB Regional direct non-exclusive 

trans . 
IBMBRDC Regional direct non- exclusive 
IBMBRDD Regional direct non-exclusive 
IBMBRJA Indexed sequential input/update 
IBMBRJB Indexed sequential input/update 
IBMBRKA Indexed direct non-exclusive 
IBMBRKB Indexed direct non-exclusive 



l£§DgS)i^!^g^ Modules 
IBMBRKC Indexed direct non-exclusive 
IBMBRLA Indexed sequential output 
IBMBRLB Indexed sequential output 
IBMBRQA Buffered consecutive 

(non-spanned) 
IBMBRQB Buffered consecutive 

(non-spanned) 
IBMBRQC Buffered consecutive 

(non-spanned) 
IBMBRQD Buffered consecutive 

(non-spanned) 
IBMBRQE Buffered consecutive input 

(spanned) 
IBMBRQF Buffered consecutive output 

(spanned) 
IBMBRQG Buffered consecutive update 

(spanned) 
IBMBRQH Buffered consecutive OMR 
IBMBRQI Buffered consecutive associated 

file 
IBMBRTP Teleprocessing file input 
IBMBRVA VSAM ESDS transmitter 
IBMBRVG VSAM KSDS sequential output 
IBMBRVH VSAM KSDS sequential input 

/update 
IBMBRVI VSAM KSDS direct transmitter 
IBMBRXA Exclusive regional direct 

update update/input 
IBMBRXB Exclusive regional direct 

update update/input 
IBMBRXC Exclusive regional direct 

update update/input 
IBMBRXD Exclusive regional direct 

update update/input 
IBMBRYA Exclusive indexed direct update 

update/input 
IBMBRYB Exclusive indexed direct update 

update/input 
IBMBRYC Exclusive indexed direct update 

update/input 
IBMBRYDA Exclusive indexed direct 

update update/input 
IBMBSOF Stream output file 
IBMBSOU Stream output file 
IBMBSOV Stream output file 
IBMBSTF Stream output print file 
IBMBSTI Stream input file 
IBMBSTU Stream output print file 
IBMBSTV stream output print file 
IBMCSTI Stream input file 
IBMCSTP Stream output file 

Record I/O error modules 

IBMBREA Record I/O error module 

IBMBREB Record I/O error module 

IBMBREC Record I/O error module 

IMBBREE Record I/O error module 

IBMBREF Record endfile module 



Figure 8.2. Library subroutines used in record I/O 



If the TOTAL option is used, the 
majority of transmission statements on 
buffered consecutive files are compiled as 
direct calls to the data management 



routines. This method is known as in-line 
I/O. When using in-line I/O, subroutines 
of the PL/I transmitters are available to 
handle error situations. The appropriate 



126 



FILE TYPE 

Buffered consecutive 
Unbuffered consecutive 
Regional sequential 

(not spanned records) 
Regional sequential 

(spanned records only) 
Regional direct 
Indexed sequential 
Indexed direct 
TP buffered input/update 
VSAM 



ACCESS METHOD 

QSAM/VSAM 
BSAM/VSAM 

BSAM 

BDAM 

BDAM 
Q I SAM/ VSAM 
BISAM/VSAM 

TCAM 
VSAM 



Consecutive or indexed files can be 
used to access VSAM data sets; the PL/I 
open routines will determine the data 
type. For details see section on OPEN 
statement. 



As can be seen from the summary above, a 
large number of library subroutines and 
control blocks are used in the 
implementation of record I/O. These are 
summarized in two figures: figure 8.2 for 
library subroutines and figure 8.4 for 
control blocks. More detailed descriptions 
for each statement type are given below. 



ACCESS METHOD 



The access method used for different PL/I 
file types is shown in figure 8.3, 



File Declaration Statements 



Figure 8.3. Access methods and file 
types 



transmitter is loaded during the file 
opening process. 



For each file declaration, a declare 
control block (DCLCB) and, optionally, an 
environment control block (ENVB) are set 
up. Both are held in static internal 
storage for internal files, or in a 
separate control section for external 
files. 



CLOSE Statements 



CLOSE statements are implemented by a call 
to the open/close bootstrap routine 
IBMBOCL, which loads and calls the 
transient close routine IBMBOCA. This 
routine disassociates the file from the 
data set, and handles the necessary 
housekeeping. 



Implicit Open 



Implicit opening is handled by manipulation 
of addresses so that any attempt to access 
the file when it is not open will result in 
control being passed to the open routines 
in the PL/I libraries. 



The DCLCB is a control block that 
contains the filename together with a 
record of the attributes obtainable from 
the file declaration, both those given 
explicitly and those deducible by default. 
This information is retained until the file 
is opened, when, unless the TOTAL option 
has been used in the file declaration, the 
information is merged with any attributes 
in the OPEN statement. 

The ENVB contains the addresses of all 
environment options. The format of the 
ENVB is given in appendix B. 

From information in the DCLCB and the 
ENVB, (and sometimes from the open control 
block (OCB) produced from the OPEN 
statement) a further control block, the 
file control_block__(FCB)_ is generated. 
During execution of an I/O statement, all 
information about the file is derived from 
the FCB. 



Implicit Close 



Execution 



Implicit closing is handled by the program 
termination routine checking for open 
files, and if it finds any, calling the 
PL/I library routine to close them. 



No executable code is produced from the 
file declaration. Figure 8.5 shows the code 
resulting from a file declaration. 



Chapter 8: Record-oriented Input/Output 127 



CONTROL BLOCKS GENERATED FROM 
FILE DECLARATION 



CONTROL BLOCK GENERATED FROM 
OPEN STATEMENT 



DCLCB 



Open control block (OCB) 



Function Holds all file attributes 

used in file declaration 

Location Separate control section 

for external files, static internal 

for internal files. 

When generated: During compilation 

Contents 

Record of file attributes 

at declaration 

File name 

Address of ENVB 

Offset of FCB pointer in PRV 



Function: To contain file attributes 
given in OPEN statement 
Location: In static storage 
When generated: During compilation 
Contents: The attributes when 
specified on the OPEN statement 



Environment control block (ENVB) 



Function: Holds information on 

environment options 

Location: In static storage 

When generated: During compilation 

Contents: Addresses of 

blocksize 

record length 

of buffer tracks 

KEYLOC value 

key length 

indexarea size 

addbuf 



Figure 8.4. (Part 1 of 2). The fields used in implementing record I/O 
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CONTROL BLOCKS GENERATED FROM 
INPUT/OUTPUT STATEMENTS 



CONTROL BLOCK GENERATED DURING 
EXECUTION OF OPEN STATEMENT 



Key descriptor (KD) 



Function: To describe the key variable 

Location: Depends on storage class of 

key variable 

When generated: Depends on storage 

class of key variable 

Contents: Length and address of key 

variable 



Record descriptor (RD) 



Function 


To describe the record variable 


Location: 


Depends on storage class of 


record variable 


When generated: Depends on storage class 


of record 


variable 


Contents: 


Length and address of record 


variable 





Request control block (RGB) 



Function: Holds a definition of the 
statement for execution-time checking 
Location: In statis storage 
When generated: During compilation, for 
library data management calls only 
Contents: Flags defining statement 

Code for TM instruction, or 
a branch instruction (if 
checking was done during 
execution) 



File control block (FCB) 



Function: Acts as a central source of 
information about the file 
Location: In statis storage 
When Generated: During open 
Contents include: 

Flags indicating 

valid statements 

Transmitter name 

Transmitter address 

Error module address 

DCB/ACB address 

Filename address 

Buffer address 

flags and workspace for 

the Xmitters 
DCB 

Data Management control block/ 

Access-Method Control Block 



Figure 8.4. (Part 2 of 2) . The fields used in implementing record I/O 
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OPEN Statement 



Library: Prograir Logic . 



Comp il er Output 



For an OPEN statement, the compiler 
generates a call to the open/close 
bootstrap routine, IBMBOCL, and an open 
control block (OCB) . The OCB holds any 
attributes that are declared in the OPEN 
statement. 

More than one file may be passed to the 
open routines. The last file has its last 
parameter flagged with its first bit set to 
•1'. 



Execution 



Actions Carried Out by Transient Open 
Routines 



The transient open routines perform the 
following major functions when opening a 
file: 

1. Build the file control block (FCB) and 
data control block (DCB) , or, for VSAM 
the access method control block (ACB) 
I for the file. The FCB is a PL/I 
I control block used to access all file 

information. Ihe DCB is a data 
1 management control block used to 
I describe the data set. The ACB is 
I the equivalent of the DCB for VSAM 
files. 



For an explicit open, a call is made to the 
open/close bootstrap routine, IBMBOCL. For 
each file to be opened, the following 
information is passed to IBMBOCL: 

The address of the DCLCB 

The address of the OCB, (or zero, if 

no OCB exists) 
The address of the TITLE, (or zero if 

none is specified) 

IBMBOCL has four entry points: 

IBMBOCLA explicit open 

IBMBOCLB implicit open for library 

call I/O 
IBMBOCLC explicit close 
IBMBCCLD implicit close 

When called by entry point A, IBMBOCL 
invokes the transient library open routines 
to open the file. If the environment option 
TOTAL has not been used in the file 
declaration, it will be necessary to 
determine the attributes of the file by 
merging the attributes in the file 
declaration with those used in the OPEN 
statement. Attributes in the file 
declaration are held in the ENVB and DCLCB. 
Attributes used in the OPEN statement are 
held in the OCB. If the TOTAL option has 
been used, attributes are taken from the 
declaration, and any contradictory 
attributes in the OPEN statement result in 
the raising of the ERROR condition. 

The open modules build an FCB and DCB 
from the information in the control blocks, 
initialize the pseudo-register vector to 
point to the FCB, load the PL/I and data 
management transmitters, and return to 
compiled code. Five transient open modules 
are used. Their functions are summarized 
below and are described in detail in the 
licensed publication OS/360 PL/I Transient 



2. Issue the data management OPEN macro 
instruction to associate the file with 
the data set. 

3. Obtain and initialize buffers and any 
other blocks required for the file. 

4. Determine which statement types are 
valid for the file, and store this 
information as a set of flags held in 
the FCB. 

5. Select the appropriate PL/I 
transmitter, and load it for use 
during transmission statements. 

6. Check for errors, and raise the 
UNDEFINEDFILE condition if any are 
found. 

7 . Place the address of the FCB in the 
correct pseudo-register vector offset. 

The execution of an OPEN statement is 
sumiiiarized in figure 8.6. 



VSAM Data Sets 



VSAM data sets both KSDS and ESDS are 
normally accessed by PL/I using VSAM iracro 
instructions, however, in certain 
circumstances the data sets are accessed 
through the compatibility interface. If 
the file is declared with ENV (VSAM) the 
VSAM macro instructions will automatically 
be used. Even if it is not so declared, the 
PL/I open modules will normally detect that 
a VSAM data set is being accessed. To do 
this they issue an RDJFCB macro 
instruction. However this action is not 
effective if the ALLOCATE command is being 
used under TSO to provide DD information. 
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DCL Fl FILE UNBUFFERED RECORD INPUT ENVIRONMENT (RECSIZE (80)); 



T 



DCLCB 

.1. 



000000000201 0200 
0106 1 9000000001 8 
000000 1 4000206 Fl 
0000000000000000 
0000000200000040 
0000004400000040 
0000004 0000040 
0000004000000040 



ENVB 



Figure 8.5. Information in the file declaration is held in the ENVB and the DCLCB 
until the file is opened 
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Open control block 
(OCB) holds options in OPEN 
statement 



Title held in static 




OPEN FILE(F2) OUTPUT TITLE COUTFILE'); 



© 



® 
® 



® 



© 



Executable instructions call to Open close bootstrap module passing parameter list ( 5 j containing addresses etc 



for (X) (2)and0 



DCLCB set up during file declaration see figure 8.5 

Open control block in static. See Appendix A for Format : 

000048 0020000000D00800 CONSTANT 
00000000 

Title (held in static internal) is addressed via locator (also in static internal) 
Title 

OOOOAO D6E4E3C6C9D3C5 
Locator 

000020 000000A000070000 

Machine Instructions 

000088 41 10 3 064 LA 1,100(0,3) Point R1 at P-lists 

00008C 58 FO 3 OOC L 15,A..IBMB0CLaI 



000090 05 EF 

Parameter list 

000064 00000044 
000068 00000000 
00006C 00000048 
000070 00000020 
000074 00000000 
000078 80000000 



BALR 14, 15 



A..CONSTANT 
A.. DCLCB 
A..CONSTANT 
A..CONSTANT 
A..NULL ARGUMENT 
A..NULL ARGUMENT 



r" Branch to open/close bootstrap 



No. of files to be opened 

A. ..OCB 

A...LOCATOR for TITLE 

Used for print files only 



From To 

compiled compiled 
code code 

i t 



EXECUTION 



IBMBOCL 



Loads transient 
open modules. 
Calls IBMBOPA 



IBMBOPA 



Open Phase I 



V 



■\r 



J V 



IBMBOPB 



Open Phase 1 1 



IBMBOPE 



Open Phase 1 1 
VSAM files 



IBMBOPC 



Open Phase 1 1 



IBMBOPD 



Open Phase IV 



IBMBOPZ 



Formatting 
(direct output 
only) 



RESIDENT LIBRARY 
Figure 8. 6. Open statement 



v 

TRANSIENT LIBRARY 
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because, in this case, the RDJFCB macro 
instruction cannot determine that a VSAM 
data set is being accessed. In this 
situation the compatibility interface will 
be used. It is possible for the user to 
force the use of the compatibility 
interface by specifying either "RECFM" or 
'•OPTCD=L'' in the AMP parameter of the DD 
statement . 

The flow through the PL/I open modules 
is as follows. IBMBOPA scans the list of 
files to be opened and sets a flag to 
indicate that IBMBOPE is required for any 
files declared with ENV (VSAM). If one or 
more files are found without ENV (VSAM), 
IBMBOPB is called to open them. Then on 
return from IBMBOPB, IBMBOPE is called to 
open any VSAM files. If IBMBOPB detects 
that any consecutive or indexed files are 
being used to access VSAM data sets, it 
will set the flag indicating that IBMBOPE 
is required and ignore that file. When all 
the non-VSAM files have been opened, 
IBMBOPD returns to IBMBOPA. IBMBOPA tests 
to see whether there are any VSAM files to 
be opened, and, if ther are, calls IBMBOPE. 

IBMBOPE opens the files starting with 
the first. Each file is completely opened 
before starting to process the next. The 
open process involves nine main steps, as 
follows : 

1. Merge attributes from OPEN 
statement with file declaration 
and check for validity. 

2. Get non-LIFO storage space for the 
FCB and ACB, and create the ACB 
using the GENCB macro instruction. 
The DDNAME is obtained from the 
filename or the TITLE option. The 
password is obtained from the 
PASSWORD environment option if 
specified. The MACRF options used 
are: 

SEQ/DIR SEQUENTIAL/DIRECT 
KEY/ADR KSDS/ESDS 
IN/OUT INPUT/OUTPUT 

(both specified 
for UPDATE) 

3. Issue an OPEN macro instruction 
and test the return codes in the 
ACB. 

4. Check the actual values of the 
RECSIZE,, KEYLENGTH, and KEYLOC 
options against any values 
specified in the ENVIRONMENT 
option. Check that NCP/STRNO is 
not greter than one. If any 
errors or descrepancies are found, 
the ACB must be closed. 

5. Set up the mask of invalid 



statements for use by IBMBRIO. 

Get non-LIFO storage space for the 
lOCB and RPL, plus key space for a 
KSDS, and a dummy buffer for a 
buffered file. Create the RPL 
using a GENCB macro instruction. 
The OPTCD values are partially set 
as shown below. The transmitter 
merges the other options according 
to statement type. The OPTCD 
options set are: 

KEY/ADR KSDS/ESDS 
SEQ/DIR SEQUENTIAL/DIRECT 
UPD/NUP UPDATE/INPUT or 

OUTPUT 
GEN/FKS GENKEY/not GENKEY 

KEQ,MVE, and ASY are always 
specified. 

Load the approptriate library 
transmitter as follows: 

ESDS IBMBRVAA 

KSDS SEQUENTIAL OUTPUT 

IBMBRVGA 
KSDS SEQUENTIAL INPUT/UPDATE 

IBMBRVHA 
KSDS DIRECT 

IBMBRVIA 

Insert "E" as the seventh 
character of the error module 
name, so that IBMBREEA will be 
loaded if an error occurs. 

Add the FCB address to the chain 
of open files and set the address 
of the FCB in the pseudo register. 



The_FCB §nd_File Addresging 



During execution of record I/O statements, 
all information about the file is obtained 
from the FCB. However, as the FCB is net 
created until execution, the FCB cannot be 
addressed directly by compiled code. 
Instead, compiled code obtains from the 
DCLCB the offset within the PRV at which 
the FCB address is held. This offset is 
placed in the DCLCB by the linkage editor. 
The mechanism is illustrated in figure 8.7. 

The use of the pseudo-register vector 
allows separately compiled programs to 
refer to the same FCB for an external file, 
even though the address of the FCB cannot 
be known until execution. An explanation 
of the use of the pseudo-register vector is 
given in chapter 2, under the heading "Use 
of the Pseudo-Register Vector." 
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R12 



TCA 




1 


r PRV 


i\ 


Address of FCB for file A 


w 


Address of FCB for file B 




Address of FCB for file C 



PL/I statement: DCL (A,B,C) FILE; 




The address of the FCB for the file is obtained by adding 
the offset in the DCLCB to the PRV address which is held 
in the TCA 



Figure 8.7. Addressing files via DCLCB and PRV 
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Transmission Statements (Library-Call 
I/O) 

Compiler Output 



For transmission statements the compiler 
generates a call to the PL/I transmitter 
interface module, IBMBRIO. IBMBRIO has the 
following parameter list passed to it: 

Address of DCLCB 

Address of request control block (RGB) 
Address of record descriptor (RD); or, 
address ignore factor; or, 
address at which to set pointer 
Address of key descriptor (KD) ; or, 

zero if no key descriptor 
Address of event variable (EV) ; or, 

zero if no event variable 
Abnormal locate return address (LOCATE 
statements only) 

The DCLCB is generated from the file 
declaration,, as described earlier in the 
chapter. The remainder of the control 
blocks in the parameter list are generated 
for the transmission statement. 

The re guest co ntr ol block (RCB) defines 
the statement type. It consists of two 
words. The first is a fullword of flags 
that define the statement type and option, 
indicating whether the statement is READ 
SET, READ INTO, WRITE FROM,, etc. The second 
word is a test-under-mask (TM) instruction 
that is executed by IBMBRIO to check 
whether the statement is valid. The flags 
in the RCB are tested against flags in the 
FCB or dummy FCB. If the statement is 
invalid, a branch is made to an address 
held in either the FCB or the dummy FCB. 
If the file is not open, the dummy FCB will 
be accessed, and the branch will be made to 
the open/close bootstrap to open the file. 
If the file is open, a real FCB will be 
accessed, and the branch will be via a 
bootstrap to the error handler. The RCB is 
set up in static internal storage. The 
format is shown in appendix B. 



The record descriptor (RD)^ contains the 

address, length and type of the record 
variable. (The record variable is the 
variable to or from which the record will 
be transmitted.) A record descriptor is 
generated only if a record variable is 
used. The format is shown in appendix B. 

The key descriptor (KD) contains the 
address and length of the key variable. 
(The key variable is the variable to or 
from which the key will be transmitted.) It 
is generated only if a key variable is 
used. The format is shown in appendix B. 

If the record variable or the key 
variable is STATIC INTERNAL, a complete RD 
or KD is set up and placed in static 
internal storage during compilation. In 
most other circumstances, a skeleton RD or 
KD will be set up,, and will be completed by 
the inclusion of the address during 
execution. The completed descriptor may be 
moved into temporary storage. In certain 
conditions, no skeleton is produced; 
instead, the complete descriptor is built 
in temporary storage by compiled code. 

The event_variable lEV). (if used) 
contains information about the event that 
has been associated with the event I/O 
statement. (For format, see appendix B.) 
The implementation of event I/O is covered 
briefly at the end of this chapter, and 
further in chapter 11 for non-multitasking 
programs and chapter 14 for multitasking 
programs. 

The abnorma 1 ^ lp.9§t e ret ur n^block is used 
only for LOCATE statements. It is the 
address of a block containing the address 
to which control will be passed if an error 
is detected in a LOCATE statement and a 
normal return is made after execution of 
the on-unit. The abnormal-locate return 
address is usually the start of the next 
statement. 

The code and control blocks generated 
for a transmission statement using a 
library call to the data management 
routines are shown in figure 8.8. 
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COMPILATION (^ 

/Z\ DCLCB ^ of 



Record descriptor 
holds address and length 



Key descriptor 

holds address and length of key variable 



DCLCB "A of record variable 
identifies file 

EQUESr CONTROL BLOCK 
holds statement type 

WRITE FILEIF) FRCJR7I(F§) KEYFROM(K); 

EXECUTABLE INSTRUCTIONS VS/ are a call to the PL/I library module IBMBRIO 
completing and passing PARAMETER LIST \!^ which holds addresses of 1, 2, 3 and 4. 




© 

© 
© 

© 



© 



DCLCB, set up from file declaration holds address of FCB via pseudo register vector. 
(See file declaration). 



REQUEST CONTROL BLOCK holds record of statement type 
000028 0880200091022001 CONSTANT 

RECORD DESCRIPTOR holds address and length of record, set up as far as possible during 
compilation, completed during execution. For statement above set up in temporary storage 
during prologue code 

KEY DESCRIPTOR holds address and length of key, set up as far as possible during 
compilation, but, for this statement, completely built by compiled code in temporary 
storage (see 5). 



Executable instruction 



* STATEMENT NUMBER 4 








000092 


41 90 


D 0B8 


LA 


9,184(0,13) 


Pick up address record descriptor 


000096 


50 90 


3 084 


ST 


9,132(0,3) 


Place in parameter list 


00009A 


41 90 


D OBO 


LA 


9,176(0,13) 


Pick up address-key descriptor 


00009E 


50 90 


3 088 


ST 


9,136(0,3) 


Place in parameter list 


0000A2 


41 10 


3 07C 


LA 


1,124(0,3) 


Point R1 at parameter list 


0000A6 


58 FO 


3 014 


L 


15,A. .IBMBRIOA 




OOOOAA 


05 EF 




BALR 


14,15 


Call IBMBRIO 



© 



Note: For this statement the record and key descriptors were set up in temporary storage 
during prologue code. 



PARAMETER LIST passed to IBMBRIO 



00007C 00000000 

000080 00000028 

000084 00000000 

000088 00000000 

00008C 00000000 

000090 80000000 



A . .DCLCB 

A. .CONSTANT 

A. .RD 

A. .KD 

A. .NULL ARGUMENT 

A. .NULL ARGUMENT 



Filled in by linkage editor 

Request control block 

(Record descriptor) 

(Key descriptor (built during execution)) 



Figure 8.8. (Part 1 of 2). Handling a transmission statement 
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EXECUTION OF TRANSMISSION STATEMENT 

Call from compiled code Return to compiled code 





1 


r 




i 


IBMBRIO 

(Resident library interface module) 
Loads parameters into registers. 
Calls PL/I transient library 
transmitter whose address is placed 
in the FCB during the execution 
of the OPEN statement. 




^ 


f 




PL/1 TRANSMITTER 

(Transient library) 
Calls data management. 
Checks for errors and moves 
record and key if necessary 






^ 


^ d 


k 




DATA MANAGEMENT 
Handle the transfer of data 





Figure 8.8. (Part 2 of 2) . Handling a transmission statement 
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Execution 



occurred. 



Compiled code calls the transmitter 
interface module, IBMBRIO, passing to it 
the parameter list shown above under 
"Compiler output". 

The interface module, IBMBRIO, first 
acquires a DSA, which is used by IBMBRIO 
and by the transmitter. It then 
initializes the registers for the 
transmitter, and executes the TM 
instruction in the request control block 
(RCB) . This instruction tests a set of 
flags that are addressed by a pseudo- 
register offset contained in the DCLCB. 
The contents of the pseudo-register offset 
depends on whether the file is open. If 
the file is not open, it is opened and 
return made to this point to continue the 
statement. (see "IMPLICIT OPEN" later in 
this chapter. ) 

When the file is open, the TM 
instruction tests the validity flags in the 
FCB. This establishes the validity of the 
statement. If the statement is not valid, 
a branch is made to the address held in the 
word in the FCB following the statement 
validity flags. This address is an entry 
point in IBMBRIO that calls the error 
handling module, IBMBERR, with an error 
code indicating an invalid statement. 

If the statement is valid, a branch is 
made to the transmitter whose address is 
held in the FCB. 



Transmitter Action 



After the file is open and the statement 
validated, control is passed to the 
transmitter, which checks the record and 
key variables for errors, and issues the 
appropriate data management macro 
instruction. After the data management 
macro instruction has been executed, 
control returns to the transmitter. The 
transmitter moves the data between the data 
management buffer and the record variable, 
or sets the pointer to the record, and 
checks to see whether any errors have 



Transmitter modules do not acquire 
separate DSAs, but use the DSA acquired by 

IBMBRIO. 

If the statement is Valid, control is 
returned to compiled code. The situation 
when an error has been detected is 
described later in this chapter under the 
heading "ERROR CONDITIONS IN TRANSMISSION 
STATEMENTS . " 

In certain conditions, data manageirent 
will require a parameter list known as the 
data event control block (DECB) . The PL/I 
library routines include this block in a 
PL/I control block known as the 
input/output control block (lOCB) . A 
number of lOCBs may be used. The number 
depends on the file type, and on the NCP 
subparameter in the DD statement or NCP 
option in the ENVIRONMENT attribute. 
Depending on the file type, lOCBs may be 
generated during the execution of the open 
statement, or by the transmitters when they 
are required. 

The format of the lOCB is shown in 
appendix A. The format of the DECB and a 
further description of its use is given in 
the publication OS/3 6 0_ Supervisor and Data 
Management_Macrg_Instruction§. lOCBs are 
further described in the section "EVENT 
OPTION", below. 



EVENT Option 



When the EVENT option is used, transmission 
statements are always handled by library 
call. The compiler generates a call to 
IBMBRIO in the usual manner, except that 
the address of an event variable is passed 
in the parameter list. 

The associated WAIT statement is 
compiled as a call to one of the library 
wait modules. The module called depends on 
whether or not the program is multitasking. 
The execution of an I/O statement with the 
EVENT option and its associated WAIT 
statement is shown in figure 8.9. 
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P : PROC; 



READ.. ..EVENT (E); 
< 



1 



<J 



IBMBRiO 



I 
V 



PL/I TRANSMITTER 



I £> 



ISSUE DATA MANAGEMENT - 

MACRO 

RETURN IF EVENT I/O 

ISSUE CHECK MACRO <3 

I 
I 



TEST FOR ERRORS 

IF NONE RETUR'NTOWAIT 

MODULE I 



1^ 

I 

V 



V 

I 
I 



WAIT(E); 

:<| 









WAIT MODULE 

IF EVENT I/O CALL IBMBRIO 



LL IBMBRIO ^> - 



RETURN IF NO MORE 
EVENTS TO WAIT ON 



ENDP; 



Key 






READ EVENT statement 
WAIT statement 
Further PL/I statements 



~1 



I 
I 

A 
I 

I 
I 



I 
I 
I 

A 
I 



I 

A 

I 
I 



Figure 8.9. Handling the EVENT option 
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Execution 



The principle used in event I/O is that the 
PL/I transmitter returns to compiled code 
as soon as the data management macro 
instruction has initiated the I/O. 

When I/O with the EVENT option is being 
executed, the event variable associated 
with the event is set active and flagged to 
indicate that the event is an I/O event. 
When the WAIT statement is reached, the 
library wait module is entered. When the 
event is an I/O event, the PL/I library 
wait routine passes control to IBMBRIO. 
From information in the event variable, 
IBMBRIO locates the I/O operation 
associated with the event, and calls the 
transmitter. The transmitter then issues a 
CHECK macro instruction, and waits until 
the operation is complete, when control 
returns after the CHECK macro instruction, 
the transmitter assigns the transmitted 
data, and either returns to the wait 
module, or, if any errors are detected, 
enters one of the error routines. (For 
further details, see "ERROR CONDITIONS IN 
TRANSMISSION STATEMENTS" later in this 
chapter.) 

When the transmitter assigns the data, 
it is necessary for the address and length 
of the record variable, and certain other 
information, to be available. This 
information is retained in the input/output 
control block (lOCB) . 



Use of the lOCB 



The lOCB is chained to the event variable 
so that the I/O routines can access the 
statement when control is returned to them 
during execution of the WAIT statement. 

To associate the PL/I statement with the 
data management operation,, the DECB for the 
operation is included in the lOCB. (The 
DECB is a record held by the data 
management routines so that the operation 
can be posted complete.) 

For certain types of PL/I files, the 
lOCB also contains the data management 
buffer to or from which the transmission 
will be made. 



Allocation of lOCBs 



For direct access files, lOCBs are 
allocated as they are required by the 
transmitter. 



For sequential access files, the lOCBs 
are generated by the open routines. The 
number of lOCBs requested corresponds to 
the number specified in the NCP 
subparameter or option. 



lOCBs and Dummy^ Records 



In event I/O, the existence of a dummy 
record may not be discovered until after a 
read has commenced on the record following 
the dummy. When this happens, the DECB and 
lOCB pointers are reset appropriately. 



E§i§iQ3_Q2S^iii2S§_iQ_^vent_I/0 



Because the CHECK macro instruction is not 
issued until the WAIT statement is 
executed, PL/I conditions raised in event 
I/O are handled during execution of the 
WAIT statement. The implications of this 
are discussed in the section on the WAIT 
statement in chapter 11 for non- 
multitasking programs, and chapter 14 for 
multitasking programs. 



Exclusive I/O 



In exclusive I/O, records are protected 
from simultaneous updates from different 
tasks by use of the ENQ and DEQ macro 
instructions. 

When a READ statement for an exclusive 
file is being executed, an ENQ macro 
instruction is issued. Unless NOLOCK is 
specified, the DEQ macro instruction is net 
issued until a REWRITE, DELETE, or UNLOCK 
statement is executed. For unblocked 
records, the ENQ and DEQ instructions are 
issued on one record only. For blocked 
records, they are issued on the data set. 

Eight PL/I transmitter modules are used 
to handle exclusive files: they are shown 
in figure 8.2. The ENQ and DEQ macro 
instructions are issued by calling the 
resident library routine IBMBPDQ, which is 
addressed from the TCA. 

The protection of the data set depends 
on all files that access the data set 
having the EXCLUSIVE attribute. If the 
data set is accessed by a file that does 
not have the EXCLUSIVE attribute, the data 
set will not be protected. 

I For VSAM files the EXCLUSIVE attribute is 
ignored and the NOLOCK option and UNLOCK 
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DCLCB identifies file to be closed 



CLOSE FILE(F2) 



©" 



Executable instructions consist of a call to the open/close bootstrap nnodule passing parameter I 



.(D 







DCLCB set up for file declaration see figure 8.5 



® 



Executable instructions 

* STATEMENT NUMBER 5 
OOOOAC 41 10 3 094 
OOOOBO 58 FO 3 010 
0000B4 05 EF 



Parameter list 



LA 1,148(0,3) 

L 15,A. .IBMBOCLC 

BALR 14,15 



Place address DCLCB in p-list 
> Call open/close toolstrap 



000094 00000044 A. .CONSTANT Address of constant showing number of files to be closed 

000098 00000000 A. .DCLCB Address DCLCB 

00009C 80000000 A. .NULL ARGUMENT Used for disposition options, flagged in first bit to indicate last argument 

CLOSE FILE(FI); 

COMPILATION 

L 7,F0 Pass address of constant with number of files to be closed 

ST 7,2528(0,3) Pass address of DCLCB of file 

LA 1,2524(0,3) Point R1 at parameter list 

L 15,A. .IBMBOCLC Branch to open/close bootstrap 

BALR 14,15 



EXECUTION 



Call from compiled code 
± 



Return to compiled code 



IBMBOCL 
Entry point C 

Resident library open/close bootstrap 
routine. Calls the close routine 



rzT 



IBMBOCA 

Transient library close routine. Calls 
transmitter to complete 1/0 if necessary. 
Calls data management to close the data 
set. Removes FCB from Open File 
Chain. Restores PRV offset to point to 
dummy FCB. 



zz 



DATA MANAGEMENT 
Disassociates file from data set. 



■^; — v: — 
s \ 



PL/I TRANSMITTER 

Transient library routine. Calls 
data management to complete I/O 



Figure 8.10. The execution of an explicit CLOSE statement 
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PRV 



DCLCB 




Initialized to dummy FCB 
Changed to real FCB when 
file is opened 



I 
^ DUMMY FCB 



Address of open/close 
bootstrap routine 



Address of open/close 
bootstrap routine 




FCB 



Address of error 
handling module 



Address of data 
management routine 



KEY 



Address contained in PRV when file open 



Address contained in PRV when file closed 



Connection between DCLCB and PRV field. 
The DCLCB contains the offset filled in by 
the linkage editor. The PRV itself is 
addressed from the TCA. 



Figure 8.11. The addressing mechanism used during implicit open 
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I statement will have no effect (except that 
I for UNLOCK, the key specification is 
I checked.) Data set protection is provided 
by VSAM itself. 



to the termination routine (for the end of 
the program) . The code and control blocks 
generated for a CLOSE statement are 
summarized in figure 8.10. 



CLOSE Statements and Implicit Close 

Compiler Output 



For CLOSE statements^ the compiler 
generates a call to the appropriate entry 
point of the open/close bootstrap module, 
passing it the addresses of the DCLCB and 
ENVB for the file. 

No compiler action is taken for implicit 
close. 



Execution 



Files and data sets can be closed either by 
the PL/I CLOSE statement or by the 
termination of the program. In both cases, 
the close is carried out by library 
routines. The bootstrap module IBMBOCL is 
called either by compiled code, or, during 
program termination,, by the termination 
routine,, IBMBPIT or IBMTPJR for 
multitasking. It loads and calls the 
transient close routine, IBMBOCA. 

The bootstrap routine IBMBOCL is passed 
a parameter list containing the addresses 
of the DCLCBs and ENVBs for the files that 
require closing. IBMBOCA then closes these 
files. This may involve completing I/O 
operations, and hence calling the 
transmitter. After handling any necessary 
transmission, IBMBOCA disassociates the 
file from the data set. 

The ENVB is required if the LEAVE or 
REREAD option is in effect. 

For implicit closing, the chain of open 
files starting in the tCA is scanned to 
determine which files must be closed. The 
addresses of the FCBs of these files are 
then passed to the close routine. 

For an explicit close, it is necessary 
to set the address in the pseudo-register 
vector to point,, once more, to the dummy 
FCB. This allows implicit opening to be 
handled should the file be opened again. 
(See "IMPLICIT OPEN" later in this 
chapter, ) 

When IBMBOCA has finished, it returns 
control (via IBMBOCL) either to compiled 
code (for an explicit close statement) or 



Implicit Open for Library -Call I/O 



Com2iler_0ut£ut 



There is no compiler output for an implicit 
open, because it is not always possible to 
predict which transmission statements will 
cause implicit opening of a file. 



Execution 



Implicit opening is handled by manipulation 
of addresses (see figure 8.11). 

When IBMBRIO is called for a 
transmission statement, it executes a test- 
under-mask (TM) instruction against a set 
of flags held at an offset from the address 
held in the pseudo-register vector. The 
address held in the pseudo-register vector 
depends on whether the file is open. If 
the file is open, the pseudo-register 
offset contains the address of the FCB for 
the file. If the file is not open, the 
pseudo-register offset contains the address 
of a dummy FCB in the program management 
area. 

The address is set during program 
initialization to point to the dummy FCB, 
and is reset to the dummy FCB whenever a 
file is closed. 

The first word in the dummy FCB is a set 
of statement validity flags. These are all 
set to zero. Consequently any TM 
instruction executed by IBMBRIO will give a 
negative result. The second word of the 
dummy FCB is the address of an entry point 
in the open/close bootstrap module. If the 
TM instruction yields a negative result, 
IBMBRIO branches to the address held 
immediately after the statement validity 
flags. Consequently when an attempt is 
made to execute a transmission statement on 
a file that is not open, control passes 
automatically to the open routines. 

The open routines open the file, and set 
up an FCB and DCB for the file. The 
address of the FCB is placed in the pseudo- 
register offset, and execution of the 
statement is reattempted by branching once 
more to IBMBRIO. 
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Error Conditions in Transmission 
statements 



To provide PL/I error handling facilities 
with the reiniirum possible overhead to 
error-free programs, transient-library 
modules are used. These are not loaded 
unless an error occurs. Two modules are 
available for every file type except VSAM: 

1. The ENDFILE routine, IBMBREF, which 
can deal only with the ENDFILE 
condition. 

2. A general error module capable of 
handling all conditions that may 
arise, including ENDFILE, but loaded 
only if the TRANSMIT, RECORD, KEY, or 
ERROR condition occurs. (See figure 
8.12.) 



Record I/O | File types 
error module | 


IBMBREA 1 Consecutive buffered 
IBMBREB 1 Indexed 

IBMBREC 1 Regional, consecutive 
1 unbuffered, and 
1 transient 

IBMBREE 1 VSAM 


Endfile module I 


IBMBREF 1 All SEQUENTIAL/ INPUT/ 
1 UPDATE file types 
1 (excluding VSAM) 



L J 



Figure 8.12. Record I/O error modules 



This method is used because the short 
ENDFILE module gives faster execution to 
those programs that use the ENDFILE 
condition to handle program flow. The 
transient error modules for all file types 
are identified by the six letters IBMBRE 
followed by a further single character (see 
figure 8.13). 

If a transmission error occurs, the 
transmission error routine within the 
transmitter will be entered, whether an in- 
line or library-call statement is being 
executed. The transmission error routine 
has been nominated in the SYNAD exit 



address placed in the DCB by the OPEN 
routines. Similarly, if end-of-file 
occurs, the end-of-file routine within the 
transmitter will be executed. Record and 
key errors are detected either by the 
transmitter or by compiled code. 

When any of the errors or PL/I 
conditions mentioned above occurs during 
the execution of a record I/O statement, 
control is passed to the address held in 
the word "FERM" in the FCB. The address may 
be any one of the following: 

• The address of IBMBREF, the ENDFILE 
module. 

• The address of the general error module 
for the file type. 

• The address of a bootstrap routine, 
IBMBRIOB. This routine constructs the 
name of an error module by taking the 
skeleton IBMBRE*A and replacing the "♦" 
by the letter in the single character 
field "FEFT" in the FCB. IBMBRIO then 
loads this error module, places the 
address of the module in FERM, and 
branches to the module. 

So, by changing the contents of the field 
FEFT, the transmitter can select a 
particular error module. The contents of 
FEFT is one of the following: 

• A character indicating the name of the 
general error module for the file type. 
This character is placed in FEFT during 
the execution of the OPEN statement. 

• The character "F", indicating the name 
of the ENDFILE module. The contents of 
FEFT is changed to "F" by the end-of- 
file routine in the transmitter, which 
is entered when data management detects 
end-of-file. 

Thus the module loaded by the bootstrap 
routine IBMBRIOB, and the address placed in 
FERM, depend on whether end-of-file or 
another error is the first to occur on the 
file. 

The result of this arrangement is that 
the general error module can be called in 
an end-of-file situation. Similarly, the 
ENDFILE module can be called when another 
type of error occurs, if ENDFILE was the 
first condition to occur. To overcome this 
problem, the general error module contains 
code to handle ENDFILE, and the ENDFILE 
module contains code to test for other 
conditions, and load and call the general 
error module if appropriate. 



IHH 



Contents FEFT 
Initialized by open routine 
with character "A", "B", "C" 
indicating general error suoport 
nnodule. 

Altered by end of file routines 
in transmitter to character "F" 
indicating ENDFILE module 



IBMBRIO 

(entry ()oint B) 
Loads and calls module 
indicated in "FEFT" and 
places its address in FERI\ 



FCB 



Contents FEMT 
Always contains character 
indicating general error 
support module 



FEFT 



FEMT 



FERM 



IBMBREF 

Endfile module 
If ENDFILE : 
Calls error handler 
If other error : 
Loads and calls 
error module indicated 
in "FEMT". Placing 
address in FERM 



IBMBRE/A/B/C 

General error support modules. 

Handle all errors including 
ENDFILE 



Key 



If no errors have occurred. 

If 1st. error was ENDFILE and 
no other errors occurred. 

If non-ENDFILE errors have 
occurred. 



Figure 8.13. The fields used in record I/O error handling 
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The ENDFILE module constructs the name 
of the general error module in a similar 
manner to that used by IBMBRIOB, described 
above. However, the sixth letter of the 
name is taken from a field in the FCB 
called "FEMT." FEMT always holds the 
character that identifies the general error 
module for the file. When the name has 
been constructed, the general module is 
loaded, its address is placed in FERM, and 
a branch is made to the module by way of 
the bootstrap routine in IBMBRIO. 



General Error Routines (Transient) 



statements." Only READ, WRITE, and LOCATE 
statements are handled in this way. OPEN 
and CLOSE statements are always executed by 
library calls. 



Control Blocks 



For in-line I/O statements, the only 
control blocks that are set up are the FCE 
and DCB. The request control block, record 
descriptor, and key descriptor are not 
required as they are merely parameters for 
library subroutines. 



The general error routines set up a 
parameter list and the relevant built-in 
function values in the ONCA (described in 
chapter 7). They then call the resident 
error handler IBMBERR to handle the 
condition. If a normal return is made from 
an on-unit, the general error module will 
raise any further conditions that have 
occurred by calling IBMBERR with the 
appropriate error code. After all 
conditions have been raised, a return is 
made to compiled code, or, in event I/O, to 
the wait module. 



ENDFILE Routine 



The ENDFILE routine checks to ensure that 
the situation which has resulted in the 
call is really end-of-file, and, if so, 
passes control to the error handler. 



TRANSMIT Condition 



For certain file types, when a permanent 
transmission error occurs action must be 
taken to prevent subsequent issuing of data 
management macro instructions. To achieve 
this, addresses are manipulated so that, 
instead of IBMBRIO calling the transmitter 
by its primary entry point, it calls an 
error routine within the transmitter, which 
in turn calls the error handler to raise 
the TRANSMIT condition. 



Executable Instructions 



For in-line I/O, a call is made direct to 
the data management routine whose address 
is held in the FCB. In addition to calling 
the data management routine, compiled cede 
moves the data as necessary to or from the 
record variable, or sets appropriate 
pointers. Compiled code may also check for 
the RECORD condition. 

For U-format and V-format records, 
compiled code does not call data management 
direct. Instead a call is made to small 
routines within the PL/I transmitters. 
These routines are addressed through the 
field in the FCB that normally addresses 
the data management routines. This field 
is initialized by the open routines when U- 
format or v-format records are used on the 
file. The compiler can thus produce the 
same code for all record types. 

For certain types of blocked file, 
deblocking is handled by compiled code. 
Fields in the DCB hold the address' of the 
current record, the address of the end of 
the block, and the record length. Before a 
call is made to data management, a check is 
made to see whether the end of the block 
has been reached. This is done by adding 
the record length to the current record 
address. If the resultant address is the 
end of the block, a call is made to data 
management for a new block; otherwise, the 
new address can be taken as the start of 
the required record. 



In-line I/O Statements 



Error Conditions 



Most transmission statements on buffered 
consecutive files are implemented by in- 
line calls to the data management routines 
(see figure 8.16 for details). Such 
statements are referred to as "in-line I/O 



If an error occurs during transmission, or 
if end-of-file is reached, the data 
management routines will branch to the 
ENDFILE or SYNAD routines that are held in 
the PL/I transmitter. (The PL/I 
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transmitter is always loaded by the open 
routines. ) The ENDFILE and SYNAD routines 
set an error flag in the FCB, and return to 
coitipiled code, normally via the data 
management routine. If the error flag is 
on, or if the RECORD condition has 
occurred, compiled code branches to 
IBMBRIOD. This results in a call being 
made to the transient error module. 

Typical code produced for an in-line I/O 
statement is shown in figure 8.14. 



Implicit Open for_In-Line Calls 



Implicit opening for in-line calls is 
handled in a similar way to that used for 
library calls. 

The field that,, in a normal FCB, points 
to the data management transmitter, in the 
dummy FCB points to the open/close 
bootstrap routine, IBMBOCL (see figure 
8.11). This results in a branch being made 
to the OPEN routines when an attempt is 



made to access a file that is not open. 
When the open routines have been executed, 
the address in the pseudo-register vector 
is altered to point to the FCB that has 
been created for the file. 



If the file is successfully opened, a 
test is made to see whether the entry to 
IBMBOCL was for an in-line call and, if it 
was, control is passed to the data 
management address held in the DCB. This 
causes the data management module to be 
entered and a return made to compiled code. 

A further problem arises over 
deblocking, for certain blocked files, 
before data management is called, a test is 
made to see whether the end of the block 
has been reached. For such files, values 
are placed in the dummy FCB that ensure 
that if the test for end-of-block is made 
before the file has been opened, the test 
will reveal an apparent end-of-block. A 
branch will therefore be made to the 
transmitter field in the dummy FCB, and 
control will pass to the open/close 
bootstrap routine. 
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SOURCE 


1 




EXAMPLE :PROC OPTIONS (MAIN) ; 


2 


1 


DCL LINE FILE RECORD INPUT 

ENV (FB, RECSIZE( 80 ) , BLKSIZE ( UOO ) , TOTAL) , 
CARD CHAR (80) ; 


3 


1 


READ FILE (LINE) INTO (CARD) ; 


4 


1 


END; 



♦ STATEMENT NUMBER 



00005E 


18 


72 






000060 


58 


90 


3 


01C 


000064 


18 


B9 






000066 


58 


10 


C 


u04 


00006A 


5A 


10 


B 


UOO 


00006E 


58 


20 


1 


000 


000072 


58 


10 


2 


014 


000076 


18 


81 






000078 


58 


10 


8 


04C 


00007C 


4A 


10 


8 


052 


000080 


59 


10 


8 


048 


000084 


47 


40 


7 


03A 


000088 


18 


18 






00008A 


41 


80 


3 


020 


00008E 


58 


FO 


2 


01C 


000092 


05 


EF 






000094 


47 


FO 


7 


03E 


000098 










000098 


50 


10 


8 


04C 


00009C 










00009C 


C2 


4F 


C 


0A8 


0000A2 










0000A2 


91 


80 


2 


02C 


0000A6 


47 


EO 


7 


052 


OOOOAA 


58 


FO 


3 


014 


OOOOAE 


05 


EF 






OOOOBO 










OOOOEO 


18 


27 







1 000 



CL.2 



CI. 4 



CL.3 



CL.5 



LR 

L 

LR 

L 

A 

L 

L 

LR 

I 

AH 

C 

EL 

IR 

LA 

I 

EALR 

B 

EQU 

ST 

EQU 

NVC 

EQU 

TM 

ENO 

I 

BALR 

EQU 

LR 



7 2 

9,'28(0,3) 

11,9 

1,4(0,12) 

1,0(0,11) 

2,0(0, 1) 

1,20(0,2) 

8,1 

1,76(0,8) 

1,82(0,8) 

1,72(0,8) 

CL.2 

1,8 

8,32(0,3) 

15,28(0,2) 

14,15 

CL.4 

1,76(0,8) 

*• 

CABC(80) ,0( 

44(2), X'80' 

CL.5 

15, A. .lEMBR 

14, 15 

* 

2,7 



Save program base 

Load R9 address of DCLCB 

Load Rll DCLCB 

Load Rl PRV 

Add PRV offset in DCLCB to address in Rl 

Point R2 at FCB 

Point Rl at DCB 

Save address of DCB 

Pick up pointer to current record (start of deblocking) 

Add logical record length to access required record 

C-ompare with end of buffer 

Branch around data management call if new buffer not required 

Restore DCB address if new buffer required 

Pass abnormal return address (CL.3) in R8 for error handling 

Load address of data management routine 

Branch and link to data management routine 

Branch around next instruction 

Label branched to if no data management call 

Point Rl at required record 

1 ) Move record into record variable 



Test for errors 
branch if no errors 
ICD if errors call error bootstrap routine 

restore program base 



Figure 8.14. In-line i/o transmission statement 
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SOURCE 
PROGRAM 



Open 
statement 



ovyiviri UM I lOIV 



Transmission 
I/O statement 



Generate code 
to call open 
bootstrap 



Set up RGB 
for Execution- 
Time test 



Generate 

in-line 

code 



In-line 




LIBRARY 



Set up RGB 
with code to 
branch found 
Execution-Time 
test 



Generate 
call to 
IBMBRIO 





Path using library calls 
Path for in-line I/O 
Gommon path, in-line/library 




• • • • 


— _ 


Path for implicit open 



Figure 8.15. Overview of record I/O 



EXECUTION 



COMPiLED CODt 



Gall 
IBMBOGL 



Gall 
IBMBRIO 



LIBRARY AND DATA MANAGEMENT MODULES 



EXPLICIT OPEN 



IMPLICIT OPEN 

^_ 



IBMBOGL 



Pass control 
block addresses 
to IBMBOPA 



IBMBRIO 



Branch to 
ERROR 
handler 
(IBMBERRA) 
or open 
bootstrap if 
file not open 




YES 



TM 
Instruction 



Execute 
Instruction 
in RGB 



Branch 
instruction 



i 



IBMBOPA, etc. 



Library calls 



Associate file 
with data set 
Load trans- 
mitter 
— 1 r- 



J 






In-line calls 



CONTINUE 



TRANSMITTER 



Gall data 

management 

routine 



Error routines 
set flags 
indicating error 
has occurred 



Move record 
key etc. Check 
for record & 
key condition 




-1- 



DATA MANAGEMENT 



Carry out 
I/O 




COMPILED CODE 



J V' Gall data ^ 
^v management J 



YES 



Record I/O 
Error module 

Call 
IBMBERR 



Move record key 
etc. Check for 
record & key 
errors 



♦-4-»^ 



YES 




CONTINUE 
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r 

1 File type: Consecutive buffered 


(TOTAL option 


used) 










1 Record type: F,FB 


1 Statement 


Record variable requirements 


1 


ENVIRONMENT option requirements 


1 READ SET 


None 




1 

1 


None 








1 READ INTO 


Length known 
(max. length 
or area*) 


at compile time 1 
if a varying string 1 


RECSIZE known 
SCALARVARYING 
string 


at compile time 
option if varying 


1 WRITE FROM 

1 (fixed string) 


Length known 


at compile time 




RECSIZE known 


at 


compile 


time 


1 WRITE FROM 








RECSIZE known 
SCALARVARYING 


at compile time 
option used 


1 WRITE FROM 
1 Area* 








RECSIZE known 


at 


compile 


time 


1 LOCATE A 


Length known 
(max. length 
or area*) 


at compile time 1 
if varying string 1 

1 


RECSIZE known 
SCALARVARYING 


at 
if 


compile 
varying 


time 
string 


1 Record type: U/V,\ 


7B 














1 READ SET 


None 




1 


Not BACKWARDS 








1 READ INTO 


Length known 
(max. length 
or area*) 


at compile time 1 
if varying string 1 


RECSIZE known 
SCALARVARYING 


at 
if 


compile 
varying 


time 
string 


1 WRITE FROM 

1 (fixed string) 


Length known 


at compile time 




RECSIZE known 


at 


compile 


time 


1 WRITE FROM 

1 (varying string) 








RECSIZE known 
SCALARVARYING 


at compile time 
option used 


1 WRITE FROM 
1 Area* 








RECSIZE known 


at 


compile 


time 


1 LOCATE 


Length known 
(max. length 
or area*) 


at compile time 1 
if varying string 1 

1 


RECSIZE known 
SCALARVARYING 


at 
if 


compile 
varying 


time 
string 


1 Notes: All statemt 
1 or file vai 


2nts must be found to be valid during compilation, 
riables are never handled by in-line code. 


File parameters 


1 BLKSIZE ma2 
1 FB, VB) . 


f be specified 


instead of RECSIZE fo 


r F, V, and U formats (but not 


1 * Including struci 


:ures whose last element is an 


unsub 


scripted area. 









Figure 8.16. Conditions under which I/O statements are handled in-line 
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PL/I Statement: GET LIST(I); 



PL/I transmitter modules 

call LIOCS routines to move 
the data between the external 
medium and the data manage- 
ment buffer. 



External medium File SYSIN 



Data Management buffer 



10 



Stage 1 



▼ 
I 





Stage 2 



1 Conversion routines or 
I compiled code convert 
' data and move to variable. 



~l 



Director routines control the 
process, calling necessary 
conversion and transmitter 
modules when required. 



Variable I (Fixed Binary 15,0) 
(in main storage) 



Stream input/output is a two stage process. The data is moved between the external medium and the data management buffer, and 
between the buffer and the variable. Any necessary conversions are made between the buffer and the variable. The operation is 
controlled by director modules. The director modules call the appropriate routines to do the transmission and conversion. Transmission 
is carried out in a similar way to that used for RECORD I/O. 

Note that a further input statement will require the value 9 which is already in the data management buffer. Consequently the trans- 
mitter need not be called and a pointer must be kept to the position reached in the buffer. 



Figure 9.1. The principles used in stream I/O 
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Chapter 9: Stream-oriented Input/Output 



Note_on_Tern!inologY 



In this chapter, the terms source and 
target are used when referring to transfer 
of data. The source is the point from 
which the data is taken; the target is the 
point to which it is moved, possibly in a 
converted format. 



data management routines make only one 
record available to the program at any one 
time, a method is needed to build up 
complete items if they span the record 
boundary. Similarly, because GET and PUT 
statements may read or write less than a 
complete record, a method is needed of 
keeping track of the position reached in 
the record, so that the next GET or PUT can 
start from the correct position. 



Introduction 



PL/I Stream-oriented input/output allows 
the programmer to move data between a PL/I 
variable and an external medium without any 
concern about internal and external data 
types or any attention to record 
boundaries. Both conversion and record 
boundary problems are handled 
automatically . 

Although it appears to the programmer 
that the data is moved directly between the 
external medium and the PL/I variable, the 
move is, in fact, a two stage process, as 
shown in figure 9.1. In the first stage, 
the data is moved to a data management 
buffer. In the second stage, it is moved 
from the buffer to the target. When the 
data is moved to or from an external 
medium, a complete record is always moved. 
When the data is moved to or from a PL/I 
variable, only as much data as is contained 
in the variable is moved. The amount of 
data moved in the one stage need bear no 
relation to the amount moved in the other. 
Thus synchronization of the two stages is 
the principal job in implementing stream 
I/O. 

Transmission between the buffer and the 
external medium is handled by the routines 
of OS data management. These routines are 
called by the PL/I transient library 
transmitters in the same way as that used 
in library-call record I/O. The movement 
between the buffer and the PL/I variables 
is generally handled by the PL/I conversion 
routines. The transmitters and the 
conversion routines are called by director 
routines. These routines determine which 
modules are required, and when they are 
needed. 

Data items transmitted by stream I/O are 
not affected by record boundaries (see 
figure 9. 2) . There may be any number of 
data items in a record, and an item may 
span any number of records. Because the 



Operations. JLn_ a Stream I/Q_Statement 



A stream I/O operation can involve any or 
all of the following operations: 

1. Opening the file, and raising the 
ERROR condition if the statement is 
invalid. 

2. Keeping track of the position in the 
buffer. 

3. Calling the transmitter for a new 
record. 

4. Building in intermediate workspace an 
item too large to be held in the 
current record. 

5. Determining which conversion is 
required, and calling the routine to 
carry out the conversion. 

6. Enqueuing and dequeuing on SYSPRINT. 

control of operations (2) through (5) is 
handled by director routines. For list- 
directed and data-directed I/O, PL/I 
library director routines are used. For 
edit-directed I/O, the job is shared 
between library routines, compiler- 
generated subroutines, and compiled code. 

Before the director module or director 
code receives control, an 
initialization/termination module is 
called. This module handles item 1 in the 
list above: checking statement validity, 
and opening the file if it is not already 
open. The initialization/termination 
routine is also called when every PUT 
statement is completed, to dequeue on 
SYSPRINT and, for conversational files, to 
complete the output. The routine is also 
called on the completion of GET statements 
with the COPY option, to transmit the data 
to the copy file. 
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Figure 9.2. Record boundaries do not affect stream I/O 



Because there are three modes of stream 
I/O, the exact situation cannot be defined 
in a generalized discussion or diagram. 
However, the basic principles are shown in 
figure 9.3. The sequence is: 

1. A call to the initialization module, 
to check statement validity, and to 
open the file if necessary. 

2. A return to compiled code, to set up 
parameters for the director module. 

3. A call to the director module to 
handle any conversion, transmission, 
and housekeeping problems that may be 
involved. 

4. For PUT statements, a terminating call 
to the initialization/termination 
routine to dequeue on SYSPRINT. 



block is known as the stream_I/Q_control 
block (SIOCB). The contents of the SIOCB 
are shown~in figure 9.4. The SIOCB 
contains the addresses of the source and 
target (or their locators) , and of the DEDs 
of the source and the target. The SIOCB is 
passed directly to the conversion routines. 
The first four words contain the parameters 
expected by the conversion routines. 



File Handling 



In stream I/O, file organization is always 
sequential and the access method used is 
the queued sequential access method (QSAM) , 



Transmission 



Stream I/O Control Block (SIOCB) 



To simplify communication between the large 
number of routines that may be used in a 
stream I/O operation, a control block is 
set up for the duration of the execution of 
the stream I/O statement. This control 



Transmitters are called by the director 
modules or, in certain cases, by the 
initialization module, or by the close 
module to complete transmission when the 
program is terminated. 

As with record I/O, transmitters call 
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Pass A (SIOCB) 
to initializing module 
Indicate stmt type in 
SIOCB 



COMPILED CODE 




CalllBMBOCL 
to open file 
(see Ch. 8) 



Check stmt & 
return to 
compiled code 
if valid 



INITIALIZATION 
MODULE 

Checks statement validity, 
opens file if necessary 



Set AIDED) and 
A(source) 
or A (target! 
in SIOCB 



COMPILED CODE 



Call One of 

director 

modules 




Call 
transmitter 



Locate item in 
buffer 



Get 

new record 



TRANSMISSION 

Movement 
between 
buffer and 
external medium 



Convert item 
as indicated 
by DEDs 



Move to 
target 



CONVERSION 

Movement 
between 
buffer and 
variable 



Update FREM 
& FCB A buffer 
pointers in FCB 



DIRECTOR 
MODULE 

Handles complete operation 
calling transmitter and con- 
version modules as required 




COMPILED CODE 



YES 
CONTINUE 



Figure 9.3. Simplified flow diagram of a stream I/O statement 
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data itianageirent modules. The PL/I 
transmitters contain the EODAD and SYNAD 
routines, which are entered when end-of- 
file or other errors are detected in the 
routines. Nine different transmitter 
modules are used in stream I/O; these 
include two for conversational files. The 
stream I/O transmitters are listed in the 
summary of subroutines at the end of this 
chapter. 



SSRC 


Address of 
locator 


source or source 


SSDD 


Address of 


source DED 


STRG 


Address of 
locator 


target or target 


STDD 


Address of 


target DED 


SFLG 


Flag bytes 




SFCB 


Address of 


FCB for file 


SRTN 


Abnormal return address (next 
statement) 


SAVE 


save word used by compiler 


SCNT 


Count of items transmitted 
(Halfword) 


SOCA 


Address of 


ONCA 


SSTR 


Area present only for GET or PUT 
STRING, to hold a dummy file 
control block. (27 fullwords) 



L J 

Figure 9.4. Stream I/O control block 
(SIOCB) 



Opening the .File 



in the pseudo-register vector. 



Implicit Open 



Implicit opening is handled by the 
initialization routines, which check to see 
whether the file is open and, if not, call 
the open/close bootstrap routine IBMBOCL. 

The FCB for stream I/O is similar to 
that used for record I/O. However, it 
contains certain additional fields which 
are needed only for stream I/O. The most 
important of these fields are the buffer 
control fields. The format of a stream I/O 
FCB is shown in appendix A. 



Keeping Track..of . Buf f gr_jPggitJLon 



Two fields in the FCB are used to keep 
track of the position which has been 
reached in the data management buffer, and 
to indicate when a new record will be 
required. These fields are the buffer 
control fields: 

1. FCBA - points at the position reached 
in current record. 

2. FREM - number of unused bytes 
remaining in the record. 

FCBA points at the position reached in the 
record and enables the director routines to 
identify where the next input item must be 
read from, or where the next output item 
must be written. FREM contains the number 
of bytes left in a record. It enables the 
director modules to determine when ^ new 
record will be required, and whether an 
item is too large to be held in the 
remainder of the record and will 
consequently require intermediate 
workspace. Figure 9.5 illustrates the use 
of FCBA and FREM. 



The same basic method is used for opeiiing 
the file as is used for record I/O. During 
compilation, a declare control block 
(DCLCB) and an environment control block 
(ENVB) are set up. An open control block 
(OCB) is also set up if any environment 
options are declared in the OPEN statement. 
At open time, the information addressed 
from the DCLCB, ENVB, and the OCB (if any) 
is merged with any information in the DD 
statement, and an FCB is set up. The PL/I 
transmitter is loaded, and its address 
placed in the FCB. A DCB, addressed from 
the FCB, is set up. The DCB contains the 
address of the data management transmitter. 
Finally, the address of the FCB is placed 



Enqueuing and Dequeuing on SYSPRINT 



Because SYSPRINT is used as the standard 
file for error messages, it is necessary 
for output to SYSPRINT to be enqueued. 
This prevents error messages from one task 
in a PL/I program interrupting other output 
to SYSPRINT from another task. 

When SYSPRINT is used it is enqueued by 
the initialization routine. When any PUT 
statement is completed, regardless of the 
output file, a call is made to the 
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PL/I STATEMENT: 

GET FILE (SYSIN) LIST (A, B); 



80 Byte record 

In data management buffer 



^ -rCBM HDinS CURRENT PDii^mON- 



•FREn mivs Hur- 



f-lBER DK Rt:KHlHl"HG BYTES-'. \ 
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FCBA 



FCBA 



FCBA 



FCBA 

Holds address reached 



At start of first item 



after processing first item start of second item 



after processing second item 



FREM 
VALUE 



80 



FREM 
VALUE 



50 



FREM 
VALUE 



41 



FREM 
VALUE 



FREM holds number of remaining bytes 



Figure 9.5 The use of FREM and FCBA in recording buffer position 
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PUT LIST (A) 



FLOW DIAGRAM 



COMPILED CODE & NOTES 



Place address 
SIOCBin 
parameter list 



Step1 
Compiled code 



LA 9,40(0,4) 

ST 9,184(0,3) 

01 184(3),X'80' 

MVI 57(4),X'40' 

LA 1,180(0,3) 

L 15,A. . IBMBSIOAl 

BALR 14,15 i 



Load address SIOCB 
Place in p - list 
Mark end of p - list 
Set LIST OUTPUT flag 
Point R1 at p- list 
Call stream output 
initializer 



Call 

initializing 

module 



Step 2 

Initializing routine 
IBMBSIO 



The initialization routine is passed the address of the 
FCB and the address of the SIOCB. 




NO 



YES 



CalllBMBOCL 
to open file& 
load transmitter 



It opens the file if necessary and acquires the first 
record for print files. If the statement is invalid it 
calls the error handler. If the statement is valid it 
places the addresses of the ONCA and the FCB in 
the SIOCB and returns to compiled code. 




NO 



Call error 
handler 



YES 



Set FCB & 
ONCA address 
in SIOCB 



Figure 9,6. (Part 1 of 2) . Flow of control through a PUT LIST statement 
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Point R1 

at 

SIOCB 



Step 3 
Compiled code 



Put address 
of DED & 
source variable 
in SIOCB 



LA 1.40(0,4) 

LA 14,A 

LA 15,72(0,3) 

STM 14,15,0(1) 

L 15,A. . IBMBSLDAl 

BALR 14,15 J 



Point R1 at SIOCB 
Load A('A) 
Load A(DED . . A) 
Store in SIOCB 
Call LIST output 
director 




Step 4 

Director module 
IBMBSLO 



Call transistor 
for new record 



Get VDA & set 
as target for 
conversion 



NO 



The director module calls the transmitter and 
conversion modules when required and handles 
any housekeeping problems. 



Before calling the conversion module it completes 
the SIOCB with the address of the target locator 
and the address of the target DED. 
The target for the conversion is either the data 
management buffer or a VDA acquired for 
intermediate workspace. 



Set target 

address in 

SIOCB 

Call conversion 

module 



Fill record 
from VDA - 
call transmitter 




Update FCBA 
& FREM 



Continue as 
from Step 3 
until state- 
ment complete 
When complete 
call termination 
routine 



Compiled code 



If the statement is complete compiled code continues 

with the next statement. If the statement is not complete 

compiled code places new data in the SIOCB and once 

more calls the director module. 

When statement complete make terminating 

call to dequeue on SYSPRINT 



Figure 9.6. (Part 2 of 2) . Flow of control through a PUT LIST statement 
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initialization/termination routine. This 
routine then checks to see if SYSPRINT has 
been enqueued and,, if it has, dequeues it, 
by calling the DEQ routine. 



Handling the Conversions 



given in figure 9.3 and summarized above. 

This chapter first covers the 
implementation of list-directed GET and PUT 
statements in some detail, and then 
highlights the differences for data- 
directed and edit-directed I/O. 



conversions in stream I/O are normally 
handled by the library conversion package. 
The conversion package, described in 
chapter 10, consists of conversion routines 
and conversion director routines. 
Conversion director routines examine the 
DEDs of the source and the target passed in 
the argument list, and determine which 
entry point of which conversion module is 
required. Each possible conversion has a 
unique entry point in one of the conversion 
routines. For stream I/O, the argument 
list passed is contained in the first four 
words of the SIOCB. 

A number of conversion director modules 
are used exclusively by edit-directed 
stream I/O. These are called external 
gogyg^g. J-.og.,.^.4£gStors , and are listed in the 
summary of subroutines at the end of this 
chapter. Each module corresponds to a 
particular format of input or output. When 
the type of input or output has been 
determined by the director modules, the 
appropriate conversion director routine can 
be called to handle the conversion. 

In edit-directed I/O, the conversion 
required is normally predictable during 
compilation,, because it is implied in the 
format list. Consequently, the conversion 
modules can be called from compiled code 
rather than from the stream I/O director 
routines. A third possibility is that 
compiled code will handle the conversion 
in-line. 

When a library conversion module is 
required by compiled code, the conversion 
director module may be called, or the 
conversion module itself may be called 
directly. When the conversion module is 
called, compiled code must carry out the 
jobs normally handled by conversion 
director modules, that is, setting up a 
number of fields that are used in handling 
the CONVERSION condition and other PL/I 
exceptional conditions. 



Handling GET and PUT Statements 



There are considerable differences in 
detail between the handling of GET and PUT 
statements for the three different modes of 
stream I/O. A generalized impression is 



List-directed GET and PUT Statements 



PUT LIST Statement 



Implementation of a list-directed output 
statement is shown in figure 9.6. The 
process consists of five steps: 

1. Compiled code calls the initialization 
routine, passing the address of the 
DCLCB and of the SIOCB. Flags 
indicating the statement type have 
been set in the SIOCB by compiled 
code. 

2. The initialization routine, IBMBSIO, 
calls the open routine if the file is 
not open, and checks the validity of 
the statement. If the statement is 
invalid, a branch is made to the error 
handler, passing an error code 
indicating "invalid statement." This 
results in a message being generated, 
and the ERROR condition being raised. 
If the statement is valid, control is 
returned to compiled code. 

IBMBSIO also handles any format 
options, by calling the formatting 
module IBMBSPL. Control then returns 
to compiled code. 

3. Compiled code places the address of 
the source (or its locator, if the 
item is a string) and the address of 
the source DED in the SIOCB. (See 
chapter U for information on 
locators.) Compiled code then calls 
the director module. 

t\. The director module completes the 

SIOCB with the address of the target 
locator and the address of the DED of 
the target. The target locator gives 
the length required for the item. As 
the target is a character string, a 
locator will always be used for it. 
The address of the target is a 
position in the buffer. For PRINT 
files, the position is indicated in 
the tab table,, which will either have 
been set up by the programmer by use 
of PLITABS, or may be the default tab 
table in the library module IBMBSTA. 
For non-print files,, each item is 
followed by a single blank. PLITABS is 
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PL/I statements 

DCL A,B; PUT LIST (A,B) ; 



* STATEMENT NUMBER 2 



00005E 


ai 


90 


D 


0C8 


000062 


50 


90 


3 


044 


000066 


96 


80 


3 


044 


00006A 


92 


40 


D 


0D9 


00006E 


ai 


10 


3 


U40 


000072 


58 


FO 


3 


024 


000076 


05 


EF 






000078 


41 


EO 


D 


0A8 


00007C 


ai 


FO 


3 


030 


000080 


41 


10 


D 


0C8 


00008a 


50 


10 


D 


OCO 


000088 


90 


EF 


1 


000 


00008C 


58 


FO 


3 


02C 


000090 


05 


EF 






000092 


41 


EO 


D 


OAC 


000096 


58 


10 


D 


OCO 


00009A 


50 


EO 


1 


000 


00009E 


58 


FO 


3 


02C 


0000A2 


05 


EF 






OOOOAU 


58 


10 


D 


OCO 


0000A8 


58 


FO 


3 


028 


OOOOAC 


05 


EF 







LA 


9,200(0,13) 


ST 


9,68(0,3) 


01 


68(3), X'80' 


MVI 


217(13), X'40' 


LA 


1,64(0,3) 


L 


15,A..IBMBSI0A 


BALR 


14,15 


lA 


14, ii 


LA 


15, DID. .A 


LA 


1,200(0,13) 


ST 


1,192(0,13) 


STM 


14,15,0(1) 


I 


15,A..IEJVBSICA 


EALR 


14,15 


LA 


14, E 


L 


1,192(0,13) 


ST 


14,0(0,1) 


I 


15,A..IEMBSICA 


EAIR 


14,15 


I 


1,192(0,13) 


I 


15,A..IEKBSICT 


EALR 


14,15 



Pick up address of SIOCB 
Store in paramefer list 
Mark end of parameter list 
Set LIST OUTPUT flag in SIOCB 
Point R1 at SIOCB 

Branch to initializing module 

Pick up address of A 
Pick up address of DED. .A 
Place address of SIOCB in Rl 
Save address SIOCB in temp 
Store addresses in SIOCB 

Call list directed director routine 

Pick up address of B 

Point Rl at SIOCB 

Place address B in SIOCB 

Call list directed director routine 

Point Rl at SIOCB 

Make terminating call to dequeue on SYSPRINT 



Note: The DEDs for A and B have been commoned. Consequently the 
same address is kept in the SIOCB for both calls to the director 
modules. 



Figure 9.7. Code generated for typical list-directed I/O statement 
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GET DATA (A,B); 
FLOW DIAGRAM 



i 



Step 1 
Compiled code 



Set up parameter 
list, call 
initializer 



Step 2 

Input initializing module 

IBMBSII 



Set fields 
inSIOCB 




NO 



Call IBMBOCL 
to open file 



Return to 
compiled code 



COMPILED CODE & NOTES 



LA 


0,40(0,4) 


ST 


0,136(0,3) 


01 


136(3),X'80' 


MVI 


57(4),X'84' 


LA 


15,56(0,3) 


ST 


15,64(0,4) 


LA 


1,132(0,3) 


L 


15,A. .IBMBSIIA 


BALR 


14,15 



Pick up address of SIOCB 

Place in p - list 

flag last argument in p - list 

Set flag 'DATA INPUT' in 

SIOCB 

Set abnormal return 

address in SIOCB 

Point R1 at p - list 

Branch to stream 

initializing module 



The input initializing module is passed the 
address of the SIOCB and the FCB for the file. 



It checks the validity of the statement, opens 
the file and places the address of the FCB in the 
SIOCB and returns to compiled code 



Step 3 
Compiled code 



Set up p. list 

for data 

director 

consisting of 

A(SIOCB) 

A(SYMTAB,I) 

A(SYMTAB,J) 



J 



LA 


0,40(0,4) 


Pick up address of SIOCB 


ST 


0,140(0,3) 


Place address in p list 

p-list, containing addresses 
of symbol tables and 
variables already set up,in 
static 


LA 


1,140(0,3) 


Point R1 at p-list 


L 


15,A. .IBMBSOIA 


Call data-directed director 


BALR 


14,15 


module 


CL.5 


EQU* 


Abnormal locate return 
address 



Figure 9.8. (Part 1 of 2) . Handling a GET DATA statement 
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From Step 6 




Step 4 

Data - directed director 

module IBMBSDI 



Call transmitter 
setting up VDA 
if necessary 



Call IBMBERR 



Place address 
DEO and variable 
inSIOCB 



Update F REM & 
FCBA to beyond 
equal symbol 



Call list-directed 
director module 



The data directed director module is passed the 
address of the SIOCB and either a list of symbol 
table addresses or an address in the symbol tabit 
vector. 



The module reads in the name, checks that the 
name read is in the symbol tables passed and if 
not raises the NAME condition. 



When the variable is identified the module places 
the address of the target and its DED in the SIOCB 
and calls the list-directed director module passing 
it the SIOCB. 



Decide on 
conversion 
required and call 
correct module 



Steps 

List directed director 

module IBMBSLI 



The list directed module completes the operation as 
for list directed I/O 



Update FREM& 
FCBA 
Return to 
IBMBSDI 



(£ 



Repeat from 
step 4 until 
final semicolon 
found 



Step 6 

Return to IBMBSDI 



On return to the data directed module a search is 
made for the next name and the action continued 
as from step 4 until a semicolon is reached in the 
input stream 



Return to compiled code 



Figure 9.8. (Part 2 of 2). Handling a GET DATA statement 
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PL/I statements 

DCL A,B,C; PUT DATA (A,B,C) ; 



RELEVANT SECTION OF STATIC INTERNAL STORAGE MAP 



ooooao 


00000000 


A..DCLCB 


)> 


000044 


80000000 


A.. TEMP 


000048 


00000000 


A.. TEMP 






00004C 


00000058 


A..SyMTAB 




> 


000050 


0000006C 


A..SYMTAB 






000054 


80000080 


A..SYMTAB 






000058 


8500000100000030 
000000A800000000 
0001C100 


SYMBOL TABLE.. A 




00006C 


8500000100000030 
OOOOOOACOOOOOOOO 
0001C200 


SYMBOL TABLE.. B 




000080 


8500000100000030 
OOOOOOBOOOOOOOOO 


SYMBOL TABLE.. C 






0001C300 









Parameter list for IBMBSIOA 



Parameter list for IBMBSDOA 



RELEVANT SECTION OF OBJECT PROGRAM LISTING 



♦ STATEMENT NUMBER 


OOOOAE 


41 


90 


D 


0C8 


0000B2 


50 


90 


3 


044 


0000B6 


96 


80 


3 


044 


OOOOEA 


92 


80 


D 


0D9 


OOOOBE 


92 


01 


D 


ODA 


0000C2 


41 


10 


3 


040 


0000C6 


58 


FO 


3 


024 


OOOOCA 


05 


EF 






OOOOCC 


41 


«0 


E 


0C8 


OOOODO 


50 


90 


3 


048 


0000D4 


96 


80 


D 


ODB 


0000D8 


41 


10 


3 


048 


OOOODC 


58 


FO 


3 


020 


OOOOEO 


05 


EF 






0000E2 


41 


10 


D 


0C8 


0000E6 


50 


10 


D 


OCO 


OOOOEA 


58 


FO 


3 


028 


OOOOEE 


05 


EF 







LA 

ST 

01 

KVI 

MVI 

LA 

I 

EALR 

lA 

ST 

CI 

LA 

I 

EALR 

LA 

ST 

I 

EALR 



9,200 
9,68( 
68(3) 
217(1 
218(1 
1,64( 
15, A. 
14,15 
9,200 
9,72( 
219(1 
1,72( 
15, A. 
14,15 
1,200 
1,192 
15, A. 
14,15 



(0,13) 

0,3) 

,X'80' 

3),X*80» 

3),X'0r 

0,3) 

. IBMBSICA 

(0,13) 

0,3) 

3),X'80' 

0,3) 

. lEMBSDCA 



Pick up address of SIOCB 
Store in parameter list 
Mark end of parameter list 

Set data output flags 

Point Rl at parameter list 

Call initializing routine 

Pick up address of SIOCB 
Place in parameter list 
Mark end of parameter list 
Point Rl at parameter list 

Call director routine 



(0,13) 1 

(0, 13) L Make terminating call to 

. lEMBSIOT I dequeue on SYSPRINT 



Figure 9.9. Typical data-directed code 
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Handle entirely by library 
routine (IBMBSED), or use 
compiler-generated sub- 
routines? 



COMPILER 



LIBRARY 



Compiler-generated subroutines are used 
except in the cases shown opposite. Even so, 
a library routine will be called if a new record 
is required, and, generally, to handle a con- 
version. 



IBMBSED handles processing completely for: 

A-format item with implied length* 

B-format item with implied length 

C-format item 
•An exception is that A-format items with implied length are 
handled in-line if: OPT(TIME) is in effect, and the compiler 
can match the data list with the format list, and the data item 
is a character string. 



Figure 9.10. The use of the library in edit-directed I/O 
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PUT EDIT (B)(A); 



FLOW DIAGRAM 



NOTES 



Set up part of 

SIOCB. 

Call initialization 

routine IBMBSIO 



Stepi 
Compiled code 



LA 

ST 

MVI 

LA 

L 

BALR 



9,60(0. 4) 
9,848(0, 3) 
77(4), X'20' 
1,844(0, 3) 
15,A.IBMBSI0A) 
14,15 f 



Pick up address of SIOCB 
Place in parameter list 
Set "edit output" flag 
Point R1 at param. list 
Branch to initialization 
routine 




Step 2 
Initialization routine 



CaillBMBOCLto 
open file & call 
transmitter to 
get 1st record 



Test if file is opjen, and open if necessary, calling 
transmitter to locate record. 
Place address of ONCA and FOB in the SIOCB. 
Check statement validity. 



Place address of 
variable, its DED, 
& DED generated 
from format item 
in SIOCB 



Steps 
Compiled code 




LA 


ima 4) 


Point R1 at SIOCB 


LA 


14, B 


Pick up address of B 


ST 


14,0(0, 1) 


Place in SIOCB 


L 


14,76(0, 3) 


Pick up DED 


L 


7,A. . .lELCGOA 


Branch to compiler - 


BALR 


6,7 


generated subroutine 



Step 4 
lELCGOA 



Set 'VDA' flag in 
SIOCB. Get VDA 
and set as 
address of target. 



Acquire VDA for item if necessary. 

Either if there is no room in current record, or, 

if the converted item will span the record boundary. 



Figure 9.11. (Part 1 of 2). 



Edit-directed statement with matching data and 
format lists 
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FLOW DIAGRAM 



NOTES 



Carry out 
conversion either 
in - line or by 
calling library module 



i 



Steps 

Compiled code 
or conversion 
routine 



Call 
lELCGOB 



L 15,A..IBMBCHFH 

BALR 14,15 

L 7,A..IELCG0B 

BALR 6,7 



Call conversion routine 



Call compiler - generated 
director module 




Step 6 
lELCGOB 

YES 



YES 



Call IBMBSEOA 
Call transmitter 
and free VDA 



Update PR EM, 
FCBA, and FCNT 



Clear 'VDA' flag 
and IBMBSED 
flag 



Return to 
compiled code 



Update buffer control fields 
Handle housekeeping 



Continue from 
STEP 3 with next 
item, if any 
When complete 
make terminating 
calltolBMBSIOT 



Step? 
Compiled code 



Continue as necessary 

When complete call termination 

routine to dequeue on SYSPRINT 

LA 14,A. .IBMBSIOT 
BALR 14. 15 



Figure 9.11. (Part 2 of 2). 



Edit-directed statement with matching data and 
format lists 
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addressed from the TCA. 



statement is shown in figure 9.7. 



When the starting position for the 
item has been found, the director 
module determines whether there is 
enough space in the output buffer for 
the converted item. There may not be, 
for one of two reasons: 

a. The end of the buffer has been 
reached. 

b. The converted item will be too 
large to hold in the buffer. 

If the end of the buffer has been 
reached, the transmitter is called to 
acquire a new record. If the 
converted item will be too long to fit 
in the buffer, intermediate workspace 
will be needed. 

If it is simply a case of acquiring a 
new record, the director calls the 
transmitter to acquire it. The 
director then calls the appropriate 
conversion routine, passing it the 
SIOCE as a parameter list. The 
conversion routine will then move the 
data from the PL/I variable to the new 
record in the data management buffer. 

If, however, the converted item will 
span the boundary between the current 
and subsequent records, intermediate 
workspace is acquired in the form of a 
VDA (variable data area - see chapter 
6). The converted item is then placed 
in the VDA. As much of the data as 
will fit is moved from the VDA into 
the data management buffer, and a new 
record is acquired by a call to the 
output transmitter. The new record is 
then filled from the VDA. This 
process is continued until the 
complete item has been moved into 
buffers. The buffer pointers FREM and 
FCBA are updated. 

If there are further data items to be 
handled, a return is made to step (2), 
and the address of a new source field 
and its DED are placed in the SIOCB. 
This process is continued until all 
items in the data list have been 
processed. 

5. The statement is completed by a call 
to the initialization/termination 
routine. This checks to see whether 
SYSPRINT has been used and, if so, 
dequeues on SYSPRINT. For 
conversational files,, it also calls 
the transmitter to transmit any 
information that is still held in the 
buffer. 

The object code produced for a PUT LIST 



GET LIST statement 



GET LIST statements follow the same 
sequence, but the transmission is in the 
opposite direction. The main differences 
are: 

1. If record spanning is involved, the 
item is assembled in intermediate 
workspace before it is converted, 

2. A locator is built for the source 
string from the input, and the 
addresses of the locator and of a 
character DED for the source are 
placed in the SIOCB by the director 
module. The address of the target or 
its locator and the address of the 
target DED are placed in the SIOCB by 
compiled code. 

3. Unless the COPY option is being used, 
no final call is made to the 
initialization/termination routine . 



Data-directed GET and PUT Statements 



Data-directed GET and PUT statements follow 
a similar sequence to list-directed 
statements, in that there is first a call 
to the initialization module, followed by a 
call to a director routine. However, the 
data-directed director module is passed all 
the variables involved in the statement 
rather than one variable at a time, and 
handles the complete statement without 
returning to compiled code. 

The data-directed director module 
handles the reading or writing of the 
names, the equals signs, and the 
punctuation, and then calls the list- 
directed director module to handle the 
value for each variable. 

When the data-directed module has 
identified the location of the variable to 
or from which the data is to be moved,, it 
calls the list-directed director module 
which then handles the movement of the 
value of the variable. When the value of 
the variable has been transmitted,, control 
returns to the data-directed module, which 
handles the next name, determines the 
address of the variable associated with the 
name, and calls the list-directed director 
module to handle the transmission of the 
value. This process continues until the 
statement is complete. For output, the 
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director module completes the statement 
with a final semicolon. Figure 9.8 shows 
the complete process. 

The list-directed director module is 
called separately for each item. It is 
passed the SIOCB with the addresses of the 
source or target (or its locator) and the 
address of its DED correctly set up by the 
data-directed director module. The item is 
then handled as if it were a list-directed 
item. 



Identify 



the Name 



If a data list is included in the 
statement, for example: 

PUT DATA (A,B,C); 

the source or target variables are 
identified from a list of symbol tables. 
If a data list is not included in the 
statement, for example: 

PUT DATA; 

the source or target variables are 
identified from the symbol table vector. 

A symbol table associates a name with 
the address of a variable. The symbol 
table vector is a list of the symbol tables 
known in the external procedure. The items 
in a symbol table vector are arranged in 
program block order. When a symbol table 
vector is used, the address passed is the 
start of entries for items known in the 
current block. Symbol tables and the 
symbol table vector are described further 
in chapter U. Their format is shown in 
appendix A. 

The object code produced for a PUT DATA 
statement is shown in figure 9.9. 



Edit directed GET and PUT Statements 



Edit-directed I/O differs from the other 
modes of stream I/O in that the conversions 
required and the positions in the record 
where an item is to be placed or will be 
found are indicated in the format list of 
the I/O statement. 

The format list contains two related 
types of information: 

1. Th€ type and length of the item (e.g., 
F(3) , A(25), etc.), known as data 
format information. 



2. Spacing information (e.g., 

X(3) ,COL(70) ,etc.) , known as c ont rol 
format information. 

Both types of information are compiled as 
format_DEDs (or FEDs) and are passed by 
compiled code to the routines that require 
the information. 

Because the information is available 
during compilation, it is possible for the 
compiler to determine the conversions that 
will be required. It is consequently 
possible for compiled code to call the 
required conversion or conversion director 
routine, or to generate in-line conversion 
code without the assistance of a library 
director module. 



(i:9g!Bilg£z2gI?g£§feg^_§lj^^21j^4Dg§ 



To further optimize edit-directed I/O, a 
number of compiler-generated subroutines 
have been provided. They carry out the 
following functions: 

1. Keeping track of the buffer position, 
freeing and acquiring intermediate 
workspace where necessary, and calling 
the library when a new record is 
required. 

2. Handling X format control items, 
except where a new record is required. 

These compiler-generated subroutines have 
the advantage over library modules that 
they are not external, and consequently do 
not have to follow the external calling 
conventions. 

The compiler-generated subroutines are 
supported by two types of library director 
module : 

1. Two short modules, IBMBSEO and 
IBMBSEI, that interface with the 
transmitter and are called by the 
compiler-generated subroutines when a 
new record is required. 

2. A routine, IBMBSED, that handles the 
complete processing of an item (as the 
director does for list-directed I/O) . 
This routine is called when the item 
cannot be handled by the compiler- 
generated subroutines. 

The decision on whether to use compiler- 
generated subroutines or the overall 
library director module is made at compile 
time. Figure 9.10 shows the conditions 
under which each method is used. 

A typical edit-directed statement takes 
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the form: 



Matching_and_ Non-Matchinc 
Format Lists 



Data and 



5. 



A call to the initialization module to 
open the file (if necessary) , and 
check statement validity. 

A call to a compiler-generated 
subroutine to check whether a new 
record is required, and,, if so, to 
call the module IBMBSEI or IBMBSEO to 
acquire a new record by making a call 
to the transmitter. The SIOCB is 
completed with source or target DEDs 
and the addresses of the source and 
the target or their locators. 

A call to a conversion module or 
conversion director, or a compiled- 
code conversion. 

A further call to a compiler-generated 
subroutine, to update the buffer 
control fields, and free any 
intermediate workspace if spanning was 
involved. 

A terminating call to the 
initialization/termination routine. 



This sequence is illustrated in the 
annotated flowchart in figure 9.11. Figure 
9.12 shows the code generated for a GET 
EDIT statement. 



Handl in g Con t rol Format Items 



Control format items are implemented by 
calling a formatting module, and passing it 
the SIOCB containing the address of an FED 
for a control format item. There are four 
formatting modules: 

1. IBMBSPL: library routine for SKIP, 
PAGE, and LINE formats and options. 

2. IBMBSXC: library routine for X and 
COLUMN formats. 

3. lELCGOC: compiler-generated 
subroutine for X output items that do 
not span a record boundary. 

U. lELCGIA: compiler-generated 

subroutine for X input items that do 
not span a record boundary. (This 
module also has other functions; see 
the section "Compiler-generated 
Director Routines" near the end of 
this chapter.) 



In the majority of edit-directed 
statements, the data and format lists can 
be matched during compilation, since the 
programmer requires specific conversions 
for specific variables. However, it is 
possible to write statements which, because 
of iteration factors, cannot be matched at 
compile time. 

For example, in the statement 

PUT EDIT (A,B,C) (N(F(3)) ,X(10)); 

it is impossible to know at which point the 
ten-character space indicated by "X(IO)" 
will be required, without knowing the value 
of N. If the statement had been 

PUT EDIT (A,B,C) (F(3),,X(10)) ; 

the code would be compiled in the order: 
handle the conversion of a variable, handle 
an X item, handle the conversion of a 
variable, etc., until the data list was 
exhausted. However, as it is not known at 
which point the X items will be required in 
the unmatched statement, it is impossible 
to compile sequential code to handle the 
statement. Consequently, the code for each 
item is compiled separately, and branches 
are made between the code for data items 
and the code for format items as the value 
of the repetition factor indicates. In the 
example above, the branches would be made 
when the F item had been executed N times, 
and when the X item -had been executed once. 

The code sequences used for matching and 
non-matching data and format lists are 
shown in figure 9.13. 



Formatting for Print Files 



Formatting information such as page size, 
line size, page length and tab positions 
for print files are accessed by list- and 
data-directed director modules from a field 
TTAB held at offset X»50' in the TCA. The 
field holds the address of the tab table to 
be used. That is, either the PLITABS 
control section, if provided by the user, 
or the IBMBSTAB control section, if the 
default is to be used. 

The control section PLITABS can be 
provided by the user either as a control 
section which is link-edited with the 
object module or as a PL/I structure 
declared in his program as PLITABS. This 
structure is then compiled as a suitable 
control section by the optimizing compiler. 



170 



The prograrnirer may also use the default 
which is provided as a transient library 
module loaded by the open routines. The 
format of PLITABS and its default values 
are given in the programmer's guide for 
this compiler. 

When the open routines are called, they 
inspect the TCA to determine whether 
PLITABS has been provided by the user. If 
it has not, they load the transient library 
routine lEMBSTAB, which holds the default 
tab settings. When the routine is loaded, 
the address of entry point IBMBSTAB is 
placed in the TTAB field in the TCA. If 
PLITABS has been provided by the user, its 



address will have been placed in TTAB by 
the linkage editor. 



Handling Format Options 



Format options (for example, GET SKIPCU), 
PUT PAGE, GET SKIP LIST) are handled by a 
call to the appropriate entry point of the 
initialization routine. 

The initializing module calls the 
formatting module IBMBSPL to carry out the 
formatting. 
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PL/I statements 



DCL A,B; GET EDIT (A,B) (F(3) ,X(8)); 



♦ STATEMENT NUKBER 



000062 


U1 


90 


D 


oco 


000066 


50 


90 


3 


054 


00006A 


96 


80 


3 


054 


00006E 


92 


24 


D 


0D1 


000072 


41 


EO 


3 


058 


000076 


50 


EO 


D 


0D8 


00007A 


41 


10 


3 


050 


00007E 


58 


FO 


3 


030 


000082 


05 


EF 






000084 


41 


EO 


D 


0A8 


000088 


41 


FO 


3 


038 


00008C 


41 


10 


D 


OCO 


000090 


50 


10 


D 


0B8 


000094 


90 


EF 


1 


008 


000098 


41 


EO 


3 


03C 


00009C 


58 


70 


3 


OOC 


OOOOAO 


05 


67 






0000A2 


58 


FO 


3 


U2C 


0000A6" 


05 


EF 






0000A8 


58 


70 


3 


UIO 


OOOOAC 


05 


67 






OOOOAE 


41 


EO 


3 


042 


0000B2 


58 


10 


D 


0B8 


0000B6 


58 


70 


3 


OOC 


OOOOBA 


05 


67 






OOOOBC 


41 


EO 


D 


OAC 


OOOOCO 


50 


EO 


1 


008 


0OO0C4 


41 


EO 


3 


U3C 


0000C8 


58 


70 


3 


uOC 


oooocc 


05 


67 






OOOOCE 


58 


FO 


3 


02C 


0000D2 


05 


EF 






0000D4 


58 


70 


3 


010 


0000D8 


05 


67 






OOOODA 











CL.2 



lA 

ST 

01 

MVI 

LA 

ST 

LA 

L 

BALR 

LA 

LA 

LA 

ST 

STM 

LA 

L 

BALR 

L 

BALR 

L 

BALR 

LA 

L 

L 

BALR 

LA 

ST 

LA 

L 

BALR 

L 

BALR 

L 

BALR 

EQU 



9,192(0.13) 
9,84(0,3) 
84(3), X'80' 
209(13), X'24' 
14,88(0.3) 
14,216(0, 13) 
1,80(0,3) 
15,A..IBMBSIIA 
14,15 



1 4 , 1 :> , b n I 

14,60(0,3) 

7,A..IELCGIA 

6,7 

15,A. .IBMBSFIA 

14,15 

7,A..IELCGIB 

6,7 

14,66(0,3) 

1,184(0,13) 

7,A..IELCGIA 

6,7 

14, B 

14.8(0,1) 

14,60(0,3) 

7,A..IELCGIA 

6,7 

15, A.. IBMBSFIA 

14,15 

7,A..IELCGIB 

6,7 



Pick up address of SIOCB 

Store in parameter list 

Mark end of parameter list 

Set EDIT INPUT flags in SIOCB 

Pick up return address (CL.2) 

Store in SIOCB 

Point Rl at parameter list 

Call stream I/O initialization routine 

Pick up address of A 

Pick up address of DED. . .A 

Pick up address of SIOCB 

Save address of SIOCB 

Places addresses of A and DED. .A in SIOCB 

Point R14at FED 

Call compiler generated subroutine 
Call conversion director routine 

Call compiler generated subroutine- 

Pick up FED of X format item 
Pick up address of SIOCB 

Call compiler generated subroutine 

Pick up address of B 
Store in SIOCB 
Point R14 at FED 

Call compiler generated subroutine 

Call conversion director module 

Call compiler generated subroutine 
Abnormal return address 



Figure 9.12. 



Code generated for an edit-directed statement with matching data and 
format lists 
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MATCHING LISTS 

PUT EDIT (I, NAME, ACT. NO) 
(F(3),X(3),A(15),X(3), p'ZZZ9' 



HANDLE 
CONVERSION 
OF I 



HANDLE 
XITEM 



HANDLE 
CONVERSION 
OF NAME 



HANDLE 
XITEM 



HANDLE 

CONVERSION 

OF 

ACT - NO 



UNMATCHING LISTS 

PUT EDIT (AB, C, D) ((N) F (3), SKIP, A (4)); 



NO 



HANDLE 

CONVERSION 

F(3) 



YES 



HANDLE 

CONVERSION 

A(4) 



NO ^ OPERATION 
'^ ^ COMPLETE 



YES 




YES 





Figure 9.13. code sequences used for matching and non-matching data and format lists 
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Input and Output of Complete Arrays 



CONVERSION Condition 



When transmitting coitiplete arrays, it is 
uneconomical for a return to be made to 
compiled code after each item has been 
handled. Accordingly, the list- and data- 
directed director modules have a facility 
that enables them to handle complete 
arrays. The modules access the array 
multipliers, and handle the indexing from 
information held in the array descriptors. 
For edit-directed I/O, each element is 
handled separately, the necessary indexing 
being carried out by compiled code. 



PL/I Conditions in Stream I/O 



The CONVERSION condition is detected by the 
conversion modules in the PL/I library. 
(Conversions that could cause the 
CONVERSION condition are not handled in- 
line except where "NOCONVERSION" is 
specified.) CONVERSION is raised by calling 
a special library module, IBMBSCV. This 
module analyzes the type of conversion 
error, and calls the error handler with an 
appropriate error code. For input, the 
module also saves the field that caused the 
conversion; it is necessary to do so, 
because the field could be lost if an on- 
unit was entered and a further GET 
statement was executed on the same file 
which resulted in a new record being 
acquired. 



The following errors and PL/I conditions 
are particularly relevant to the 
implementation of stream I/O: TRANSMIT, 
CONVERSION, NAME (data-directed input 
only), ENDFILE, and unexpected end of file. 
Unexpected end of file occurs when the end 
of file is reached in the middle of an 
input item. 



TRANSMIT condition 



NAME Condition 



The NAME condition can occur only in data- 
directed input. It is raised by the data- 
directed director module when it cannct 
find a symbol table to match the name read 
in, or when the name is unobtainable (it 
might, for example, be out of subscript 
range.) DATAFIELD is set up, and the file 
positioned for the next read, before 
calling the error handler, with the 
appropriate error code. 



The rules for raising the TRANSMIT 
condition in stream I/O are that the 
condition shall be raised after the 
assignment or output of the potentially 
incorrect data item. Thus TRANSMIT can be 
raised on input for a data item even though 
the transmitter has not been called during 
the processing of the statement involved. 

When the TRANSMIT condition is detected 
by the data management routines, control is 
passed to the error routine in the 
transmitter,, which sets a flag in the FOB 
indicating a transmission error. For input, 
the director module inspects this flag, 
and,, if it is set,, sets a flag in the 
SIOCB. TRANSMIT is raised for every item 
that is taken from a record in the block 
with which the transmission error was 
associated. It is raised after each 
potentially incorrect value has been 
assigned. For output, TRANSMIT is raised 
by the transmitter immediately it occurs. 

A special entry point, IBMBSEIT, is used 
by the compiler-generated subroutines to 
raise the TRANSMIT condition. When called 
by this entry point, IBMBSEI calls the 
error handler with the appropriate error 
code for the TRANSMIT condition. 



ENDFILE Condi.tign and_UnexEected_End of 

File 



End of file is detected by the transmitter 
routines, which then enter the SYNAD 
routine in the transmitter. This routine 
sets a flag in the FCB. On return to the 
director modules,, the flag is tested and, 
depending on the situation in which the 
transmitter was called, ENDFILE or 
unexpected end of file is raised by calling 
the error handler. 

For unexpected end of file, the ERROR 
condition is always raised as soon as the 
end of file is detected. ENDFILE, in the 
case of list- and data-directed I/O, is not 
raised until a further attempt is made to 
read the input file. 



Built-in Functions in Stream I/O 



The built-in functions that are relevant to 
stream I/O are COUNT, DATAFIELD, ONCHAR, 
and ONSOURCE. 
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ONCHAR and ONSOURCE are dealt with in 
chapter 10, under the heading "Raising the 
CONVERSION Condition.* 

The COUNT built-in function is handled 
by the director routines. A coiant of 
transmitted items for the statement is kept 
in the SIOCB, and then copied into the FCB 
after every transmission to or from a PL/I 
variable. 

The DATAFIELD built-in function is 
handled by the data-directed director 
routine, which places the address of a 
string locator/descriptor for the offending 
field in the ONCA. The field is first 
moved to a workspace area, as the buffer 
may get lost if further stream I/O 
operations take place in an on-unit. 



The COPY Option 



The COPY option allows input data to be 
copied onto a specified output file. At 
the start of a GET statement with the COPY 
option, a flag is set in the FCB, and the 
current buffer position is saved in the 
field FCPM in the FCB. 

A resident library routine, IBMBSCP, is 
used to handle the data, and to transmit it 
to the copy file by calling the 
appropriate • transmitter. IBMBSCP is 
called at the end of the GET statement, and 
during the statement if a new buffer is 
acquired. The data transmitted to the copy 
file is that which is held between the 
pointers FCPM and FCBA. FCBA points to the 
next byte to be read; FCPM points to the 
start of the data to be copied. FCPM is 
updated to point to the start of the new 
buffer when a transmitter call is made 
during the execution of the statement. The 
copy flag is turned off during the 
terminating call to IBMBSII. 

If an interrupt occurs during the 
execution of a GET statement with the COPY 
option, it is possible that the terminating 
call to IBMBSII will be bypassed because of 
a GOTO from an on-unit, or because the job 
is terminated. For this reason,, a test is 
made on the copy flag at the start of every 
GET statement, and when the file is closed. 
If the copy flag is on, IBMBSCP is called 
to handle the data. When the data has been 
transmitted,, the flag is turned off. 



During the initializing call, IBMBSII 
determines whether the copy file is open 



and, if it is not, calls IBMBOCL to open 
the file. The address of the DCLCB for the 
copy file is then stored in the FCB of the 
input file. The data is transmitted to the 
file by calling the transmitter for the 
file type. 



The STRING Option 



The STRING option allows data to be 
transmitted between a string and one or 
more PL/I variables by means of a stream 
I/O statement. 

The STRING option is implemented by 
treating the string specified in the 
statement as if it were the buffer, and the 
other PL/I variables as if they were the 
sources or targets. The differences in 
housekeeping between string and file 
operations are resolved by the use of a 
string housekeeping routine, IBMBSIS. 
IBMBSIS is called in the place of the 
stream I/O initialization/termination 
routine. IBMBSIS sets up a dummy FCB that 
is initialized so that the correct action 
is taken should the director modules 
attempt to read or write beyond the end of 
the string. After the dummy FCB has been 
initialized, the director modules are 
called to convert and move the data as in 
normal stream I/O. 

To implement the string option, compiled 
code passes the string housekeeping module 
an extended SIOCB in which the dummy FCB is 
created. The buffer control fields FCBA 
and FREM in the dummy FCB are set up as if 
the string were a record. The field that, 
in a normal FCB, would hold the address of 
the transmitter, holds addresses of other 
sections of code. 

For a PUT STRING statement, the 
transmitter address field is initialized to 
point to the error handler. Register 1 will 
have been pointed to the head of the FCB by 
the caller. The error code for exceeding 
string size is, therefore, placed at the 
head of the FCB, and the correct error 
condition is automatically raised when the 
branch to the error handler is made. 

For a GET STRING statement, the address 
in the transmitter field is the address of 
code that sets the end-of-file flag and 
returns to the caller. This code is held 
within the dummy FCB* 

As far as the caller is concerned, 
attempting to read beyond the end of the 
string is equivalent to finding an end-of- 
file mark in a stream I/O statement. Where 
the ENDFILE condition or unexpected end of 
file would be raised for a stream file, a 
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GET LIST FILE (SYSIN) (STRINGl) 
COPYFILEIA): 



GET LIST FILE (SYSIN) (STRING2) 
COPY FILE (A); 



GET LIST FILE (SYSIN) (STRINGS) 
COPY FILE (B); 



FCBA 







— — — — — _ _, 




pointer for start of COPY data 




















DATA FOR COPYING ONTO' 


FILE 




NAMED A' 


DATA FOR COPYING ONTO FILE B' 




1 


























pointer fo 



Data is transmitted to the copy file at the end of each statement and at those 
times when it can no longer be held between the pointers FCBA and FCPM. 
In the example above this will be at the end of each GET statement and at 
the end of the first record. 



Figure 9.14. The current buffer pointer FCBA and FCPM, the copy pointer,, keep track 
of the data to be copied 
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•GET STRING SIZE EXCEEDED' message is 
generated, and the ERROR condition is 
raised. 



Completing. String-handling^OEgrations 



One or more further calls may be made to 
the string housekeeping routine IB^5BSIS at 
entry point T, to update the string 
characteristics after a data item has been 
transmitted. 

PyT_statements with_f ixed-length._strings; 
IBMBSIS is called after^the first item has 
been assigned to the string, to pad the 
remainder of the string with blanks. 

P,yT__statements with varying^strings : 
IBMBSIS is called to update the length of 
the string after each data item is 
transmitted. 

GET_.5tatements__with varying string : 
IBMBSIS is always called. 

The need to make a further call to 
IBMBSIS is flagged in the SIOCB when 
IBMBSIS is called to initialize a 
statement. The library director routines 
and the compiler-generated subroutines test 
this flag, and call IBMBSIS if necessary. 



The Time-Sharing Option and 
Conversational Files 



When using the time-sharing option, the 
PL/I programmer can attach the foreground 
terminal as the input or output device used 
by one or more stream files. 

Three transient library routines are 
used to implement this facility. Two are 
transmitters that are used to interface 
with TSO using the appropriate macro 
instructions to effect the input and 
output. The third module is a formatting 
module that overcomes the special 
formatting difficulties that arise when 
working at a terminal . 

When the file is opened, the OPEN 
routine tests every stream I/O file to see 
whether it is to be associated with a 
terminal. If the file is to be associated 
with a terminal,, the appropriate 
conversational transmitter is loaded: 

IBMBSIC for input 
IBMBSOC for output 

A flag is set in the FCB of the file to 
indicate that the file is a conversational 



file. 

The two transmitter modules handle the 
input, output, and prompting. Formatting 
differences between conversational and 
normal I/O are handled by a transient 
library routine, IBMBSPC. This routine is 
called by the formatting routine, IBMBSPL, 
when a conversational file is being 
handled. 

If a conversational module is used, its 
address is placed in the TCA loaded-module 
list. 



CONVERSATIONAL TRANSMITTER MODULES 



Output Transmitter IBMBSOC 



The output module IBMBSOC is similar to 
other output transmitters except that it 
interfaces with TSO, and uses the TPUT 
macro instruction. The macro instruction 
is used with the WAIT option to ensure 
proper queueing of output to the terminal. 



In2ut_Transmitter_IBMBSIC 



The input transmitter carries out a similar 
function to other PL/I input transmitters. 
However, it also has to handle certain 
prompting functions, and implements certain 
facilities required only for conversational 
output. 

IIlEBt- Input is achieved by issuing a TGET 
macro instruction to the TSO control 
program. 

Prompting : Prompting is carried out before 
every input statement, unless the last 
character transmitted to the foreground 
terminal was a colon. At the start of a 
statement, the prompting sequence is: skip 
to a new line, print a colon, and skip to 
the start of the next line. If the GET 
statement is not completed by the data 
transmitted from the terminal, a further 
call to the transmitter will be made by the 
director module handling the stream I/O. A 
further prompt is then issued to the 
programmer. Second and subsequent prompts 
take the form of a plus character followed 
by a colon. 

Prompts are issued by placing the 
required prompt-code in a suitable field, 
and using a TPUT macro instruction with a 
HOLD option. This ensures that any 
terminal output from previously executed 
PUT statements will appear at the terminal 
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before the user is prompted to enter his 
input. 

The prompt is issued to the foreground 
terminal irrespective of whether a PL/I 
output file is associated with the 
terminal. 



'new line* characters in the output buffer, 
and to call the transmitter to transmit the 
buffer contents. (In the special case of 
SKIP(O), backspace characters are used.) 

The normal PL/I rules for ENDPAGE apply 
to formatted terminal output. ENDPAGE is 
not raised for squashed mode output. 



FORMATTING 



TO simplify terminal usage various methods 
of data input are allowed that do not 
conform strictly to PL/I language 
specifications. For example list-directed 
input need not have a delimiting comma or 
blank and the trailing blanks need not be 
entered if a character item in edit- 
directed I/O does not fill the specified 
field width. 



Formatting Module IBMBSPC 



To simplify the use of a terminal, default 
formatting conventions are assumed. These 
apply to PAGE, SKIP, and LINE instructions 
and can be summarized as follows: 

SKIP instructions of 3 lines or less 
are followed, 

PAGE and LINE, and SKIP instructions 
of more than 3 lines are interpreted 
as SKIP (3) instructions. 

This default formatting can be overridden 
by the use of a PLITABS structure that 
specifies a value of 1 or greater for the 
page length. (PLITABS is described above 
under the heading "Formatting for Print 
Files.") 

IBMBSPC checks the page-length value in 
the PLITABS control section. This control 
section will be either the default taken 
from the PL/I transient library module 
IBMBSTAB, or, if the values have been 
specified by tbe programmer, will be the 
values in the structure declared with the 
name PLITABS, or, possibly, a link-edited 
control section called PLITABS. In the 
library module IBMBSTAB, the page- length 
value is zero. 

If the page-length value in the PLITABS 
control section is zero, the formatting 
conventions described above are used. 
These are referred to as squashed mode. If 
the value is greater than zero, normal 
formatting is undertaken. 

The method of formatting used is for 
IBMBSPC to insert the required number of 



Summary of Subroutines Used 

This section gives a summary of the 
subroutines used in the implementation of 
stream-oriented input/output. Detailed 
descriptions of the library modules are 
given in the relevant program logic 
manuals. 

Ten different types of subroutine are 
used in stream I/O. They are: 

1. Initializing modules 

2. Director modules 

3. Transmitter modules 

4. Formatting modules 

5. Conversion modules 

6. External conversion director modules 

7. Conversational modules 

8. The conversion fix-up module (IBMBSCV) 

9. The copy module (IBMBSCP) 

10. The string housekeeping module 
(IBMBSIS) 

Conversion modules are described in chapter 
10 of this manual. The other types of 
module are dealt with below. 



INITIALIZING MODULES 



Initializing modules initialize the streair 
I/O statement. There are two of these 
modules: 

IBMBSII - input initializer 
IBMBSIO - output initializer 

A further module is used for string 
handling. See below under "Miscellaneous 
Routines." 

IBMBSII and IBMBSIO are described 
earlier in this chapter. 
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DIRECTOR MODULES 



hihL§iEl Director _Routines 



IBMBSLI - list-directed input 
Entry point A: element item 
Entry point B: complete array 

IBMBSLO - list-directed output 
Entry point A: element item 
Entry point B: complete array 

IBMBSDI - data-directed input 
Entry point A; with data list 
Entry point B: all known variables 

IBMBSDO - data-directed output 

Entry point A: element variables and 

whole arrays 
Entry point B: single array elements 
Entry point C: all known variables and 

SIGNAL CHECK output 
Entry point D: CHECK output for a 

single item 
Entry point T: output a final 

semicolon only. 



Modules Used with Compiler-generated 

Subroutines 



IBMBSEI - edit-directed input 

Entry point A; housekeeping for input 

item spanning a record 

boundary. 
Entry point T: raise TRANSMIT for 

spanning input item 

IBMBSEO - edit-directed output housekeeping 
for output item spanning a record 
boundary. 



M odule .for ..complete Library Control of 
Edit-directed I/O of a Single Item 



IBMBSED 
Entry point A: edit-directed input 
Entry point Bi edit-directed output 



edit-directed data item, by 
freeing a VDA if one was used, 
updating the COUNT built-in 
function value, and calling 
IBMBSEIT if TRANSMIT has been 
raised. 

For output: 

lELCGOA - provides the address of the 

target of an edit-directed data 
item. 

lELCGOB - completes the transmission of an 
edit-directed data item, updating 
the buffer items in the DCLCB, 
counting the data item, and 
freeing a VDA if one was used. 



TRANSMITTER MODULES 



The actual movement of the data between the 
external medium and the buffer area is 
carried out by a series of seven 
transmitter modules, which interface with 
the routines of OS data management. These 
modules essentially complete the setting up 
of the DCB, and issue the data management 
GET and PUT macro instructions, thus 
reading or writing one record. 

One module is used for input, six for 
output. The output modules are divided into 
two groups: one group for PL/I print 
files, the other for all other output 
files. Both output module groups contain 
three modules: one for F-forroat records, 
one for V- format records, and one for U- 
format records. All modules interface with 
the queued sequential access method. 

The following transmitters are used: 

IBMBSTI - input transmitter 

IBMBSOF - output transmitter for F- format 
records 

IBMBSOV - output transmitter for V- format 
records 

IBMBSOU - output transmitter for U-format 
records 



For input: 

lELCGIA - provides the address of the 

source of an edit-directed data 
or X-format item. 

lELCGIB - completes the transmission of an 



IBMBSTF - print transmitter for F- format 
records 

IBMBSTV - print transmitter for V- format 
records 

IBMBSTU - print transmitter for U-format 
records 
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FORMATTING MODULES 



Formatting modules control the position of 
the data on the external medium. There are 
three formatting modules: two library 
subroutines, and one compiler-generated 
subroutine. 



Library _.Subroutines 



IBMBSPL - PAGE, LINE, and SKIP format items 
and options 
Entry point A: PAGE option or format 

item 
Entry point B: LINE option or format 

item 
Entry point C: SKIP option or format 
item 

IBMBSXC - X and COLUMN format items 
Entry point A: X format input 
Entry point B: X format output 
Entry point C: COLUMN format input 
Entry point D; COLUMN format output 



routines are used exclusively in edit- 
directed I/O: 

IBMBSAI - input A, B, and P character 

formats 
IBMBSAO - output A, B, and P character 

formats ' 
IBMBSCI - input C format 
IBMBSCO - output C format 
IBMBSFI - input F and E formats 
IBMBSFO - output F and E formats 
IBMBSPI - input P format arithmetic 
IBMBSPO - output P format arithmetic 



CONVERSATIONAL MODULES 



Transmitters: 

IBMBSIC - input transmitter 
IBMBSOC - output transmitter 

Formatting module: 

IBMBSPC - formatting module 



Compiler-generated Subroutine 



lELCGOC - X items, in edit-directed output, 
that do not span a record boundary. 



EXTERNAL CONVERSION DIRECTOR MODULES 



The following external conversion director 



MISCELLANEOUS MODULES 

The other subroutines used in stream I/O 
are: 

IBMBSCV - the conversion fix-up module 

IBMBSCP - the copy module 

IBMBSIS - the string housekeeping module 
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Chapter 10: Data Conversion 
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In this chapter, the terms source and 
target are used when referring to transfer 
of data. The source is the point from 
which the data is taken; the target is the 
point to which it is moved, possibly in a 
converted format. 

The PL/I language specifies situations 
in which conversion of data types will be 
carried out. These include the execution 
of stream I/O and assignment statements, 
and the evaluation of expressions that 
include different types of data. The large 
number of data types allowed in the PL/I 
language means that some 170 types of 
conversion are possible. How these 
conversions are handled by the PL/ I 
Optimizing Compiler depends, to some 
extent, on the optimization specified for 
the program. 

If optimization has been specified, all 
conversions that can be handled by in-line 
code are so handled. If optimization has 
not been specified,, the simpler and more 
commonly used conversions will be handled 
in-line,, the remainder by the library 
conversion package. 

This chapter describes the library 
conversion package and explains how in-line 
conversions are handled. It concludes with 
a description of how the CONVERSION 
condition is raised. 

Before conversions can be understood, 
knowledge of the way in which data types 
are held is necessary. This is summarized 
in figure 10.1. 



The Library Conversion Package 



The library conversion package consists of 
some 26 modules and is capable of handling 
all the conversions that are allowed in the 
OS PL/I Optimizing Compiler implementation 
of the PL/I language. All but seven of the 
modules convert data from one data type to 
another. As there are approximately 170 
possible conversions and only 19 conversion 
modules, many conversions are done by using 
a series of modules. For instance, to 
convert from fixed-decimal to bit-string 
involves an intermediate conversion to 
floating-point. The conversion package 
also contains five 



Data attributes | Stored internally as 



BIT(n) 



BIT(n) VARYING 



CHARACTER (n) 



CHARACTER (n) 
VARYING 



FIXED DECIMAL (p,q) 



FIXED BINARY (p,q) 



FLOAT DECIMAL (p) 



FLOAT BINARY (p) 



PICTURE 



Aligned: one byte 
for each group of 
eight bits or part 
thereof. 

Unaligned: as irany 
bits as are 
required, regardless 
of byte boundaries. 

As BITCn) , with 
two-byte prefix 
containing current 
length of string. 

One byte per 
character. 

As CHARACTER (n), 
with two-byte prefix 
containing current 
length of string. 

Packed decimal: 
1/2-byte per digit, 
plus 1/2-byte for 
sign. 

p <= 15: half word 
p>15: fullword 

p<=6: short 
floating-point 
p>6: long 
floating-point 
p>16: extended 

p<=21: short 
floating-point 
p>21: long 
floating-point 
p>53: extended 

One byte for each 
picture character 
(except K and V) 



Figure 10.1. 



Internal forms of data 
types 



control and utility modules, and two 
modules used for stream I/O. The stream 
I/O modules move character and bit strings 
between the data management buffer and the 
PL/I variable when no conversion is 
necessary. 

A full description of the routines in 
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the library conversion package is given in 
the publication OS PL/I .Resident^ Library ; 

The conversion paths followed for every 
conversion are known to the compiler, and 
ESD records are generated for all the 
modules that will be used. In certain 
cases, however, the data types involved are 
not known at compile time. Examples of 
this are data-directed and list-directed 
input, and edit-directed input or output 
when format and data lists cannot be 
matched. In such cases, the compiler 
generates ESD records for all conversion 
modules that could possibly be needed. 



Conversion Module ..Naming Cgnyentions 



All names begin with the letters 'IBMB'. 
The fifth letter is 'C for conversions,, 
conversion utilities, and the 
string/arithmetic directors. It is 'S' for 
the edit-directed format directors. The 
modules in the arithmetic conversion 
package have six letter names, the sixth 
letter being an arbitrary module 
identifier. The string conversion modules 
and conversion utilities have seven letter 
names in which the sixth and seventh 
letters are mnemonic; The mnemonic codes 
follow: 

X fixed binary 

F float 

I integer or binary constant 

if in c module 

I input if in S module 

D fixed decimal 

Z free decimal or float decimal 

P fixed pictured decimal 

E float pictured decimal 

H decimal constant 

Y float decimal constant on output 

B bit 

J bit constant 

C character 

Q pictured character 

A arithmetic 

output in S module 

G "check" or utility 

T table 



been entered. The method used is for each 
module to have a number of entry points. 
Each one is entered for a certain type of 
conversion, and each one implies the 
subsequent entry points to be invoked for 
that particular conversion. For instance, 
the module IBMBCE handles fixed-decimal to 
fixed-binary conversions. If the module is 
entered to carry out this conversion, entry 
point IBMBCEDX is called. However, if it 
is only an intermediate stage in a 
conversion from fixed-decimal to bit- 
string, the entry point IBMBCEDB will be 
called. When the conversion to floating- 
point is completed, the conversion to bit 
will be carried out by the module IBMBCR. 

In addition to the use of various entry 
points to specify the conversion path to be 
taken, there are two control modules to 
handle the conversion paths between 
character-string and arithmetic data. 



HOUSEKEEPING WHEN MORE THAN ONE MODULE 
IS USED 



When more than one arithmetic conversion 
module is used in a conversion, a method of 
minimizing the housekeeping has been 
evolved. This avoids saving registers and 
acquiring workspace for each module 
entered. The same library workspace is 
used for all modules in a single conversion 
operation. The first module in the chain 
saves the registers and acquires workspace; 
the last module frees the workspace and 
restores the registers. 

A simple method is used to allow each 
module to test whether or not it can use 
the previous module's workspace. A bit at a 
fixed offset from register 13 is tested. 
If the module is the first to be called, 
this bit will be a bit in the calling 
procedure's DSA, which is always set to 
zero. If the module is not the first to be 
called, the bit will be in library 
workspace and will have been set to one by 
the previous module if the same workspace 
can be used. If the module is the first, 
library workspace will be acquired in the 
usual manner. If the module is not the 
first, a branch will be made around this 
code. 



SPECIFYING A CONVERSION PATH 



ARGUMENTS PASSED TO THE CONVERSION 
ROUTINES 



When a number of conversion modules need to 
be used for a certain conversion, it is 
necessary for there to be some control of 
the path taken after the first module has 



Each conversion routine expects a standard 
set of arguments. These consist of the 
address of the source and target, and the 
addresses of the DEDs (data element 
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r 

1 Conversion 

1 ____— — _..___a.^ 1 


Comments and conditions j 


1 

Optimization | 


1 Source 
1 


1 
Target | 


SIZE 
disabled 


1 

SIZE I 
enabled | 


1 


Fixed binary 


- 


- 


1 


1 

1 

1 


Fixed decimal 


If either scale factor = and the 
other factor < 0, the optimization 
can be 'none'. 


time 


time 1 


1 

(Fixed binary 

1 


Floating-point 


If source scale factor = 0, the 
optimization can be 'none* (whether 
SIZE is enabled or not) . 


time 


time 1 


1 


Bit string 


String must be fixed-length, aligned, 
and with length <20a8. 


- 


not done] 
in-line | 


j 


Character string 
or picture 


Source scale factor must be < 0. 
String must be fixed-length with 
length ^256. Picture type 1, 2, or 3. 


time 


not done| 
in line j 


j 


Fixed binary 


If source and target scales have the 
same sign and are non-zero, the 
optimization (SIZE disabled) must be 
'time' . 




time I 


1 


Fixed decimal 


- 


- 


1 


I Fixed decimal 


Floating-point 


Source precision must be <10. 


time 


time 1 


1 


Bit string 


Source scale factor must be zero. 
String must be fixed-length, aligned, 
and with length <20a8. 


— 


not donej 
in-line j 


1 


Character string 


Source scale factor must be > 0. 
String must be fixed-length and 
length <256. 


time 


time 1 


j 


Picture 


Picture type 1, 2, or 3. For 
picture types 1 and 2 with no sign, 
optimization can be 'none*. 


time 


not done] 
in-line | 


1 


Fixed binary 


- 


time 


not donej 
in-line j 


1 


Fixed decimal 


Target precision must be <9. 


time 


not donej 
in-line j 


jFloating- 
1 point 


1 Floating-point 


Source and target may be single or 
double length. 


1 


1 




|Bit string 


String must be fixed-length, aligned, 
and with length <2048. 


time 


not done j 
in-line | 




1 Fixed binary 


[Source string must be fixed-length, 
aligned, and with length <2048. 


- 


not done j 
in-line | 


|Bit string 


1 Fixed decimal and 
1 floating-point 


[Source must be fixed-length, aligned, 
and with length <32. 


time 


not done | 
in-line j 



Figure 10.2. (Part 1 of 2). Data conversions performed in-line 
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Conversion | | Optimization 


————————————————————— ~————— ——— 1 Comrnents ano Conditions | ———— ——_-.————-.——— — 

source 1 Target | j SIZE | SIZE 

1 1 1 disabled! enabled 


1 Character string | String must be fixed-length with | - | - 
1 1 length <256. | | 
Picture | j | j 

1 Picture | Pictures must be identical. | - | - 


1 Fixed binary | source precision must be <10. | time |not done 
1 1 1 1 in-line 

1 joptimization must be 'time'. | jin-line 
Picture j 1 | j 
type 1 1 1 1 1 
(See note j j j j 
below) II II 

1 Floating-point | Source precision must be <10. | time j not done 
1 I 1 jin-line 

1 Picture | Picture type 1, 2 or 3. j time j not done 
1 1 1 1 in-line 


Locator | Locator | - 1 ~ 1 ~ 


Label 1 Label | - 1 ~ 1 "" 



I The word "time" in the columns headed "Optimization" indicates that the conversion is 
done in-line only if optimization has been specified; "not done in-line" indicates 
that the conversion is done by library call. 

L . J 

Figure 10.2. (Part 2 of 2). Data conversions performed in-line 



descriptors) for the source and the target. 
Arguments are passed in a list addressed by 
register 1. (The source is the variable or 
constant that requires conversion; the 
target is the area where the converted 
result is to be placed.) 

The DEDs are used to describe the data 
type of the element. Those passed to the 
library conversion package are set up by 
compiled code in the constants pool. They 
are described in chapter 4 and fully mapped 
in appendix A. 



module. When information is passed between 
two conversion modules using the same 
workspace, registers are normally used 
rather than a parameter list. 

In some arithmetic conversions to 
string, precision data is passed through 
certain modules that do not themselves need 
such data. 



FREE DECIMAL FORMAT 



COMMUNICATION BETWEEN MODULES 



When the conversion path goes through a 
series of modules, the address of the final 
target must be retained until the last 
module is reached. 

Temporary targets and DEDs are created 
for the intermediate results, and these are 
passed on as the source for the next 



Because all floating-^point data is in 
binary form, there is no direct 
representation of the PL/I floating-point 
decimal format. In order to simplify 
certain conversions,, a simulated floating- 
point decimal format is employed by the 
optimizing compiler. This format is termed 
free decimal (sometimes known as packed 
intermediate decimal) . The format of free 
decimal is~a 17-digit packed decimal 
mantissa and a fullword binary exponent. 
Conversions to and from free decimal form 



184 



In-line Conversions 



j Conversion | 
1 number 


Conversion 


1 2 


Fixed-binary to 
floating-point 


1 3 


Floating-point to 
fixed-binary 


1 ^ 1 


Fixed-decimal to 
floating-point 


1 5 


Floating-point to 
fixed-decimal 


1 6 


Fixed-binary to 
fixed-decimal 


1 7 


Fixed-decimal to 
fixed-binary 


1 B 


Character-string to 
fixed-decimal 


1 9 


Character-string to 
floating-point 


1 10 


Character-string to 
fixed-binary 


1 12 


Fixed-decimal to 
character-string 


1 14 


Bit-string to 
character-string 


1 15 


Fixed-binary to bit-string 


1 16 


Floating-point to bit-string 


1 17 


Bit-string to fixed-binary 


1 18 


Fixed-decimal to picture 
type 1 


1 19 


Fixed-decimal to picture 
type 2 


1 20 


1 Fixed-decimal to picture 
type 3 


1 21 


1 Picture type 1 to 
1 fixed-decimal 


iNote: Conv< 
|not used. 


srsions numbers 1, 11, and 13 



Figure 10.3. Fundamental in-line 
conversions 



an integral part of the arithmetic 
conversion package. 



The optimizing compiler generates in-line 
code for the more commonly used 
conversions. Eighteen basic types of 
conversion are handled in-line. Several of 
these basic types are used in conjunction, 
to enable a total of 28 conversions to be 
handled in-line. The circumstances in 
which in-line conversions are used are 
shown in figure 10.2. 

An example of the way in which a 
compiler conversion is used to convert from 
fixed-binary to fixed-decimal is given 
below. A list of the eighteen fundamental 
compiler conversions is given in figure 
10.3. 



Note about Picture Variables 



Not all the picture characters available 
may be used in a picture involved in an in- 
line arithmetic conversion. The only ones 
permitted are: 

V and 9 

Drifting or non-drifting characters $ 
S + - 

Zero suppression characters Z ♦ 

Punctuation characters , . / B 

For in-line conversions, pictures with 
this subset of characters are divided into 
three types: 

Picture type 1: Pictures of all 9s with 

(optionally) a V and a leading or 
trailing sign. For example: 

•99V999*, •99', •S99V9», 
•99V*», '$999' 

Picture type 2: Pictures with zero 
suppression characters and 
(optionally) punctuation 
characters and a sign character. 
Also, type 1 pictures with 
punctuation characters. For 
example: 

•ZZZ', •♦♦/**9', 'ZZ9V.99', 
•+ZZ.ZZZ*, •$///99', '9.9" 

Picture type 3: Pictures with drifting 
strings and (optionally) 
punctuation characters and a sign 
character. For example: 

•$$$$•, '-,—9', •S/SS/S9', 
•♦++9V.9*, •$$$9-« 
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sometinies a picture conversion is not 
performed in-line even though the picture 
is one of the above types, because it has 
certain characteristics that necessitate a 
subroutine call. These may be, for 
instance: 

• There is no overlap between the digit 
positions in the source and target. For 
example: 



DECIMAL (6,8) or DECIMAL (5, -3) to 
PIC •999V99* will not be performed 
in temp. 



Punctuation between a drifting Z or a 
drifting ♦ and the first 9 is not 
preceded by a V. For example: 



•ZZ.99' 



Drifting or zero suppression characters 
to the right of the decimal point. For 
example: 

'ZZV.ZZ*, '•••+V++' 



Example: Fixed7Binary tp Fixed-Decimal (cgmpiler_Conversion..No... 6) 

The conversion is performed by converting from binary to decimal via a CVD instruction, 
with a scale-matching operation (to line up the decimal and binary points) either before 
or after the CVD (or occasionally both). This scale-matching- operation is done by shifts 
where possible but, depending on scales and precision, a decimal multiplier is sometimes 
used. 

DCL SOURCE FIXED BINARY (31,9), 

TARGET FIXED DECIMAL (15,-6); 
TARGET=SOURCE; 



L 14, SOURCE 

LTR ia,iu 

BNM compiler label 

A 14, Constant 

SRA 14,9 

CVD 14,WKSP*8 

XC TARGET ( 3 ) , TARGET 

MVC TARGET+3(5)„WKSP+8 

MVN TARGET+7 (1) ,WKSP+15 



Determination 
Branch if >0 

Add a constant to negative source 
Divide by source scale (2**9) 
Convert to decimal in workspace 
Set zeros in target 
Transfer value to target 
Transfer the sign 
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r _ , 

conversion required | compiler conversions used 


Fixed-decimal to bit-string | No. 7 Fixed-decimal to fixed-binary 

i No. 15 Fixed-binary to bit-string 


Floating-point to bit-string | No. 3 Floating-point to fixed-binary 

1 No. 15 Fixed-binary to bit-string 


1 No. 6 Fixed-binary to fixed-decimal 


Bit-string to floating-point | No. 17 Bit-string to fixed-binary 

1 No. 2 Fixed-binary to floating-point 


1 No. 15 Fixed-binary to bit-string 


Fixed-binary to character-string | No. 6 Fixed-binary to fixed-decimal 

j No. 12 Fixed-decimal to character-string 


1 No. 18, 19, or 20 Fixed-decimal to picture 


Floating-point to decimal j No. 5 Floating-point to fixed-decimal 
picture | 

1 No. 18, 19, or 20 Fixed-decimal to picture 

>•> — -. — _•>■._ — — _»__ — —._— — •_._.. — -fU — _—•._____.•-._ — — — — — ____._ — — ^__ — _ — — ____.. — __ — — _ — — _ — — •_— _. 


1 No. 7 Fixed-decimal to fixed-binary 


Decimal picture to floating- | No. 21 Picture to fixed-decimal 
point 1 

1 No. 4 Fixed-decimal to floating-point 


picture | 

1 NO. 18, 19, or 20 Fixed-decimal to picture 



L — J 



Figure 10. U. Multiple conversions 



MULTIPLE CONVERSIONS 



The conversions listed in figure 10. 3 can 
be regarded as fundamental types. A number 
of other conversions can be performed by 
using two fundamental conversions in 
series. These are shown in figure 10. t. 



HYBRID CONVERSION 



This is floating-point to character-string, 
which requires an interpretive routine to 
analyze the floating-point data (as 
distinct from the attributes, which all the 
others use) , in order to generate the 
correct scale factor. This is done by the 
library, because in-line code would use the 
same algorithm. However, partial 
optimization is carried out by setting up a 
character string of the correct length 
before calling the library,, and then 
handling the subsequent string assignment 
in-line. 



Finally,, there is one hybrid conversion 
that is carried out partially in-line. 
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Raising the Conversion Condition 



also be placed in the ONCA. 



The PL/I language specifies that when an 
invalid conversion is attempted on 
character -string data, the CONVERSION 
condition will be raised unless CONVERSION 
has been disabled. 

When the CONVERSION condition has been 
raised, the language allows the program to 
access the invalid field or character by 
use of the ONSOURCE or ONCHAR built-in 
function. The language also stipulates 
that conversion should be attempted again 
if an on-unit is entered in which the 
ONSOURCE or ONCHAR pseudovariable is used 
to change the invalid field or character. 

Raising the CONVERSION condition 
involves a number of housekeeping problems, 
which are handled by a special conversion 
module,, IBMBSCV. IBMBSCV is never called 
by compiled code, since conversions that 
could raise the CONVERSION condition are 
not attempted in-line unless the CONVERSION 
condition is disabled. IBMBSCV produces the 
correct error code for the error handler, 
IBMBERR, and looks after the housekeeping 
problems. 

IBMBSCV saves considerable overheads 
being carried either by all types of errors 
or by all correct conversions. The reason 
for the overhead lies principally in the 
facility offered by the language of using 
the ONSOURCE and ONCHAR built-in functions 
to access and optionally change the field 
causing the error, and subsequently 
reattempting the conversion on the changed 
field. 

Before any conversion in which the 
CONVERSION condition could be raised is 
attempted, the ONSOURCE field in the ONCA 
must be set up, and the address at which a 
reattempted conversion should begin roust 



The code carrying out the conversion 
must then test the validity of the field tc 
be converted and, if it is invalid, set the 
ONCHAR field in the ONCA to the first 
invalid character. The module IBMBSCV is 
then called to diagnose the conversion and 
produce the correct error code for the 
error handler. There are some twenty 
possible error codes associated with the 
CONVERSION condition. 

If the condition was raised during the 
execution of stream input, further action 
is necessary. This is because an on-unit 
may specify further input, and the buffer 
which contains the ONSOURCE field may be 
lost. For example the on-unit might be: 

ON CONVERSION BEGIN; 
ON CONVERSION SYSTEM; /♦ PREVENTS 
RECURSIVE ENTRY*/ 

GET LIST (KEYB) ; 

IF KEYB< 200 THEN ONCHAR =*1'; 

ELSE ONCHAR =*9»; 

END; 

If KEYB was in the next record, the source 
field that caused the conversion would be 
lost. To prevent this, a VDA is acquired 
in the LIFO stack, and the source field is 
stored in this VDA. The ONSOURCE and 
ONCHAR pointers are altered to point to the 
field in the VDA, and all further 
operations are carried out on this field. 

The NAB pointer associated with the 
block in which the interrupt occurred must 
then be altered so that it encompasses the 
VDA. The fact that the NAB pointer has 
been altered must be known in the block for 
a GOTO out of block to be handled. The 
reset-NAB bit is accordingly set to one in 
the relevant DSA. When these opere^tions are 
complete, IBMBSCV calls the error- handling 
module IBMBERR. 
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In addition to employing the PL/I libraries 
for the functions described in previous 
chapters, the OS PL/I Optimizing compiler 
calls on a large number of computational 
and data-handling subroutines and on 
subroutines that provide interfaces with 
the operating system for such functions as 
TIME and DATE. These miscellaneous library 
calls are discussed in this chapter. The 
library subroutines themselves are fully 
described in the publications IBM 

§YStem/36 0j0pera ting. .System; PL/I Resident 

Library _Program_Logic and IBM System/360 

QPg£§^Jlgg System: PL/I Transient Library 

Prograin_Logic. ~ 

This chapter is divided into two main 
sections: the first deals with the 
computational and data-handling 
subroutines, and the second with 
miscellaneous system interfaces. 



Computational and Data-handling 
Subroutines 



The computational and data-handling 
subroutines are used to handle all the 
mathematical built-in functions, the 
majority of arithmetic built-in functions, 
and a number of array-handling, structure- 
handling, and string-handling functions. 
The extent to which library calls are used 
depends on the level of optimization 
specified by the programmer, the type of 
data involved, and, for string functions, 
on whether STRINGRANGE and STRINGSIZE are 
enabled. 



ARITHMETIC AND MATHEMATICAL SUBROUTINES 



The compiler always uses library 
subroutines for mathematical functions. 
The use of compiled code in these 
circumstances is impracticable. Where 
possible, arithmetic functions are handled 
by in-line code. The circumstances in 
which library subroutines are used for 
arithmetic functions are listed in figure 



11.1. 

Considerable use is made of chains of 
library modules to carry out the various 
functions. For example, the subroutines 
that handle complex arithmetic normally 
call on those that handle real values tc 
process each part of a complex number; 
similarly, the square-root subroutine is 
used in the computation of several of the 
trigonometrical functions. 

Arguments are passed to the arithmetic 
and mathematical subroutines either in 
registers or in a parameter list addressed 
from register 1. The use of registers 
results in faster execution, but allows 
less flexibility in use of the routines. 
Compiled code always passes arguments in a 
parameter list. All built-in functions, 
except the STRING built-in function, have 
their arguments passed in a list comprising 
the addresses of the source and target (and 
sometimes also the addresses of DEDs) . 
Computational routines are always carried 
out in floating-point unless otherwise 
indicated. This may involve conversion 
before calling the routine. 



ARRAY, STRING, AND STRUCTURE 
SUBROUTINES 



A number of array, string, and structure 
subroutines are included in the OS PL/I 
Resident Libary. These are used to carry 
out certain of the array and string built- 
in functions and a number of other 
operations. Where possible, in-line code is 
generated to carry out these functions. 
However, the enablement of STRINGSIZE, the 
use of unaligned bit strings, and the use 
of adjustable and certain varying-length 
strings will result in calls being made to 
the library sub-routines. 

The subroutines involved in these 
functions are shown in figure 11.2. Two of 
them, IBMBAIH and IBMBAMM, are concerned 
with the handling of data aggregates rather 
than with the execution of specific 
operations. They are discussed below. 
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REAL ARGUMENTS 



Function 



Data type 



Module 
name 



When used 



Integer exponentiation 



General exponentiation 



Short floating-point 
Long floating-point 
Extended 

floating-point 

Short floating-point 
Long floating-point 
Extended 

floating-point 



IBMBMXS 
IBMBMXL 
IBMBMXE 



IBMBMYS 
IBMBMYL 
IBMBMYE 



When exponent is a variable 
When exponent is a variable 
Always 



Always 
Always 
Always 



COMPLEX ARGUMENTS 



Function 



Data type 



Module 
name 



When used 



Integer exponentiation 



General exponentiation 



Short floating-point 
Long floating-point 
Extended 

floating-point 

Short floating-point 
Long floating-point 
Extended 

floating-point 



IBMBMXW 
IBMBMXY 
IBMBMXZ 



IBMBMYX 
IBMBMYY 
IBMBMYZ 



When exponent is a variable 
When exponent is a variable 
Always 



Always 
Always 
Always 



Figure 11.1. Arithmetic operations performed by library subroutines 



Handling Interleaved,_Arrays__j:iBMBAIH) 



IBMBAIH is used to assist the other library 
array-handling subroutines to process 
interleaved arrays. It is not called by 
compiled code. 

Interleaved arrays are arrays whose 
elements are not held contiguously in 
storage. They occur in arrays of 
structures. For example, the declaration: 

DCL 1 STRUCTURE (2), 
2 A(2), 
2 B ; 

would result in successive storage 
locations being allocated to elements of A 
and B as follows : 

A(l,l) ,A(1,2),,B(1),A(2,1),A(2,2)„B(2) 

Both A and B are interleaved arrays, A is 
a two-dimensional array, the first row of 
which is separated from the second by an 



element of B. As can be seen, the elements 
of A are not contiguous, nor is there a 
fixed interval between their addresses. 

The interval between the addresses of 
elements of an interleaved array referred 
to by varying only the final subscript is 
always fixed, and these elements can be 
stepped through by using the last 
multiplier from the array descriptor. 
However, such groups of contiguous elements 
are not themselves necessarily contiguous. 



When IBMBAIH is called, it is passed, 
the number of dimensions in the array, the 
address of the array descriptor, and the 
address of a work area in which to 
construct a table. Basically, IBMBAIH 
calculates the extent of each dimension and 
enters this information in the table; it 
then calculates the increments that must be 
added in order to step between elements 
that may be non-contiguous (see figure 
11.3). The information in the completed 
table is used by the calling module to 
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IBMBAAH I ALL and ANY built-in 

I functions 

IBMBAIH I Indexer for interleaved 

I arrays 

IBMBAMM I Structure mapping 

IBMBANM I STRING built-in function 

IBMBAPC I PROD built-in function 

I (fixed-point integer) 

IBMBAPF I PROD built-in function 

I (short or long 

I floating-point) 

IBMBAPE I PROD built-in function 

I (extended floating-point) 

IBMBAPM I STRING pseudo-variable 

IBMBASC I SUM built-in function 

I (fixed-point) 

IBMBASF I SUM built-in function (short 

I or long floating-point) 

IBMBASE I SUM built-in function 

I (extended floating-point) 

IBMBAYF j POLY built-in function 

I (short or long 

I floating-point) 

IBMBAYE I POLY built-in function 

i (extended floating-point) 

IBMBBBA I AND and OR logical 

I operations (aligned bit 

I strings) 

IBMBBBC I Compare aligned bit strings 

IBMBBBN I Invert aligned bit string 

I (NOT) 

IBMBBCI I INDEX built-in function 

I (character string) 

IBMBBCK ) Concatenate character 

I strings and REPEAT built-in 

I function 

IBMBBCT I TRANSLATE built-in function 

I (character string) 

IBMBBCV I VERIFY built-in function 

I (character string) 

IBMBBGB I BOOL built-in function 

IBMBBGC I compare unaligned bit 

i strings 

IBMBBGF I Bit-string assignment 

I (aligned, source and target) 

IBMBBGI I INDEX built-in function (bit 

I string) 

IBMBBGK I Concatenate bit strings, 

I REPEAT built-in function, 

I and assign 

IBMBBGS I Produces SLD (SUBSTR 

I built-in function) 

IBMBBGT I TRANSLATE built-in function 

i (bit string) 

IBMBBGV I VERIFY built-in function 

I (bit string) 



Structure_Mapping_J_IBMBAMM) 



Structures are normally mapped during 
compilation. However, certain structures 
that contain adjustable strings or arrays 
cannot be mapped until the actual lengths 
or bounds are known. Compiled code calls 
on the module IBMBAMM to carry out this 
mapping. There are four entry points: 

IBMBAMMA Compute length of structure. 

IBMBAMMB Map Structure in PL/I manner. 

IBMBAMMC Map Structure in COBOL manner 

(for interlanguage comunication 
or for files declared with the 
COBOL option) . 

IBMBAMMD Map Structure declared with 
REFER option. 



Miscellaneous System Interfaces 



In addition to the system interface used 
for input and output, the PL/I Optimizing 
Compiler makes use of a number of other 
system facilities. These are for the 
DELAY, DISPLAY, and WAIT statements, the 
TIME and DATE built-in functions, and the 
sort/merge and checkpoint/restart built-in 
subroutines. 

Calls to these facilities are made 
through library subroutines held in the OS 
PL/I Resident Library. These subroutines 
act as an interface, issuing any SVC calls 
that may be necessary, and handling 
housekeeping problems. The descriptions of 
the subroutines in this chapter are kept to 
a minimum except where the housekeeping 
problems are large and have a major effect 
on the contents of main storage. In these 
cases, background information is given and 
the various control blocks are explained, 
thus enabling the situation during 
execution to be understood. 

The OS macro instructions referred to 
below are described in IBM System/360 
0£eratin3_SYStem£___SuEervisor_and_Data 
Management ..Macro Instructions . 



TIME 



Figure 11.2. 



Array, structure, and 
string subroutines 



address successive elements of the array 
using simple code. 



The PL/I TIME built-in function is 
implemented by issuing a GETIME macro 
instruction. This is done by the module 
IBMBJTT. 

On entry from compiled code, register 1 



Chapter 11: Miscellaneous Library Subroutines and System Interfaces 191 



points to the address of the character- 
string target. The TIME macro instruction 
is issued using the TU parameter. The time 
is returned in units of 26.04 microseconds 
and the module converts this into PL/I 
defined format • hhmmssttt ' in character 
format. 



DATE 



The PL/I DATE built-in function is 
implemented by module IBMBJDT. 

On entry from compiled code, register 1 
points to the address of the date character 
string. The TIME macro instruction is 
issued. On return register 1 contains the 
date in yydddc packed decimal format. The 
year is placed in the target character 
string in character form. The day of the 
year is then compared against a table 
indicating the number of days in each 
month. If the year is a leap year the 
number of days for February is set to 29 in 
the table. The days and months are then 
set in the character string and the result 
returned to compiled code in the form 
yymmdd . 



DELAY 



The PL/I DELAY Statement is implemented by 
calling the DELAY module IBMBJDY. Register 
1 is pointed at the milliseconds delay 
required. The milliseconds are converted 
into units of 26 microseconds and the 
result stored in a fullword addressed by 
the TUINTVL parameter in the STIMER macro 
instruction. The STIMER macro instruction 
is then activated and the delay started. 
After the delay control is returned to the 
calling program. 



DISPLAY 



The PL/I DISPLAY statement is implemented 
by the module IBMBJDS. There are two entry 
points: 

1. IBMBJDSA - entry from compiled code. 

2. IBMBJDSB - entry from IBMBJWT or 
IBMTJWT when a WAIT for the EVENT is 
reached. 

If the parameter list passed to the module 
has one element, then the entry is for 
DISPLAY only, and a VDA is obtained. If 
there are two parameters, then the entry is 



for DISPLAY REPLY and a VDA is again 
obtained. If there are three parameters, 
then the entry is for DISPLAY REPLY EVENT. 
If the event variable is active ERROR is 
raised. If the event variable is inactive 
it is set active, I/O display and 
incomplete, and non-LIFO storage is 
obtained in which to build the parameter 
list. 

Next the reply buffer, if present, is 
filled with blanks and, if the reply string 
is variable length, its current length is 
set to the maximum length. The parameter 
list to the WTO macro is now built in the 
storage obtained, the address of the ECB 
put into the event variable if there is 
one, and a WTO macro issued. Finally, if 
DISPLAY REPLY without EVENT was specified, 
a WAIT macro is issued for the ECB. Return 
is then made to compiled code. 



SORT/MERGE 



The PL/I programmer can make use of the OS 
sort/merge facilities through a call to the 
built-in subroutine PLISORT. The method of 
using the facility is fully described in 
the publication IBM System/360 Operating 

System j^ PL/I Optimizing Compiler 

Prog ra mmer s.* .guide . 

The OS sort/merge program includes a 
number of user_exits that can be 
conveniently thought of as allowing the 
programmer to writ6 sections of code that 
become included in the sort/merge routines. 
Two of these user exits can be used by the 
PL/I programmer: user exit 15 allows 
records to be set up by PL/I and passed to 
the SORT routines; user exit 35 allows 
records that have been sorted to be passed 
to and processed by the PL/I program. 

Exits are not allowed in the PL/I 
language. To overcome this problem, code 
is inserted between the sort/merge modules 
and the PL/I routines. A bootstrap module, 
IBMBKST, is used, and this module acts as 
an interface between SORT and PL/I. The 
bootstrap module saves the PL/I environment 
and restores it on return from sort/merge 
so that the PL/I exit-15 or exit-35 code 
can operate in a PL/I environment. 
Similarly, the bootstrap module restores 
the environment for SORT on return from the 
exit. 

Saving and restoring the environment 
consists of replacing the address of the 
error handler in the TCA with the address 
of an error routine in IBMBKST, and vice- 
versa. 
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Declaration 



Storage 



DECLARE 



1 X(2), 
2 C, 
2 Y (2), 

3 Z (3), 
3 B; 



Incn 



Inci 



Inc- 



c 






Z(1,1,1) 


M3 ^^ ^^ 


Z(1,1,2) 


M2 




Z<1,1,3) 




B 




Z (1,2,1) 


Mi 


Z (1,2,2) 


5 




Z(1,2, 3) 




B 




C 


r 


Z(2, 1,1) 




Z(2, 1,2) 




Z(2, 1,3) 




B 




Z (2, 2, 1 ) 




Z (2, 2, 2) 




Z (2, 2, 3) 




B 





Z is a three-dimensional interleaved array, for which 

iyii , M2, and M3 = multipliers held in array descriptor (see chapter 4) 



Inc^ and Inc2 



intervals between addresses of successive elements of Z when subscripts 
for first and second dimensions, respectively, change 



The increment when the subscript for the ith dimension changes is computed as follows: 

InCj = M, - Ej^i * Mj+i + lnCi+1 

Where £, + ^ is the extent of the (i+1 )th dimension. 

Increment table for array Z (as initialized by IBMBAIH) 

subscript count 



2nd dimension 



1st dimension 



Inc, 



InCi 



extent of dimension 
increment 

subscript count 
extent of dimension 
increment 



Note: IBMBAIH returns the extent of the nth dimension in register 1. (In this example, the extent of 
the 3rcl dimension = 3.) 



Figure 11.3. Indexing interleaved arrays 
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Housekee£in2_Problen3S 



Various housekeeping problems occur in the 
user exit procedures, since there is no DSA 
chain through the SORT modules. 
Particularly difficult is the handling of a 
GOTO out of the exit procedure that passes 
control to a procedure that was activated 
before the procedure that originally called 
the sort program. This action implicitly 
terminates SORT. However, SORT will not be 
terminated by standard PL/I action, since 
it does not function in the PL/I 
environment . 

The problems are overcome by setting up 
a chainback that omits the SORT DSAs and 
includes a DSA that is specially flagged so 
that it can be recognized by the GOTO code. 
The chaining of save areas in shown in 
figure 11.4. 

When IBMBKST is called an area of 
workspace is acquired by the bootstrap 
routine IBMBKST. This consists of one 
level of library workspace, which is 
flagged and chained to look like two DSAs. 

If the SORT program is terminated by a 
GOTO out of the block that contains the 
PL/I exit program, the SORT routine has to 
be terminated before the GOTO can be 
completed. This is done by the GOTO 
routine looking for a specially flagged DSA 
in the chain. This is the second save area 
of IBMBKST. If one is found, a return code 
of 8 is set up and return made to the SORT 
routine. If there is a GOTO or an error, 
then error code 16 is set instead of 8 if 
the SORT program product being used is that 
which supports this return code to exits. 
This results in the termination of the SORT 
routine, and the GOTO can then be continued 
in the usual manner by following the DSA 
backchain through the bootstrap routine 
until the target DSA is reached. 

For handling on-units in the exit 
procedure, the DSA chain can be followed 
without reference to SORT. 



Restoration of the PL/I Environment on 
Exit from SORT 



When an exit is made from SORT, it is 



necessary to restore the PL/I environment. 
The method used is to have code that 
restores the registers at the point to 
which SORT makes its exit. Use is made of 
the SORT exit table shown in figure 11.4. 
Whichever exit is taken, control passes to 
this code. The code saves the registers 
passed by SORT and restores the registers 
of the bootstrap module IBMBKST, thus 
restoring the PL/I environment. The save 
area of the SORT bootstrap routine is 
addressed by means of an offset from the 
code that is being executed. This is 
possible because the SORT exit table and 
the register save area are both held in the 
same workspace at a fixed offset from each 
other. The code is not included in the 
bootstrap module,, in order to preserve 
reentrancy. 

If there is an error in SORT, control is 
also passed to code which restores the 
environment, and passes control to IBMBKST 
and then to IBMBERR. 



Summary of Work Done by the SORT Module 



Before calling the SORT program, IBMBKST 
does the following: 

1. Obtains a VDA for two DSAs. 

2. Creates a parameter list suitable for 
SORT. 

3. Sets up addressability code for exit 
routine, if any. 

4. Changes the interrupt handler address 
so that an interrupt results in entry 
being made to a section of the sort 
bootstrap. The sort bootstrap then 
determines the error, puts out a 
message to SYSPRINT indicating that a 
program check has occurred during the 
execution of SORT, and then terminates 
the program. 

When a SORT E35 or El5 exit is being 
taken, the addressability code saves the 
registers of SORT and reestablishes the 
PL/I environment,, and then branches to an 
entry point of IBMBKST, which: 
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Figure im. DSA chaining during the execution of SORT 
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Save registers in SORT save area. 
Restore registers for bootstrap. 
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On entry from SORT 

Reset program-check exit 

for PL/I. 

Set up parameters for exit 

routine from information 

passed by SORT. 

Cat! exit routine. 



On entry from exit routine 

Reset program-check exit 
for return to SORT. 
Arrange parameters for SORT. 
Restore SORT registers. 
Return to SORT. 



Carry out processing — return to SORT bootstrap. 



Figure 11.5. summary of action during use of a SORT exit 
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1. Restores the PL/I interrupt handler 
address, so that control will pass to 
the PL/I error-handling routines if a 
program interrupt occurs. 

2. Sets up parameters for the PL/I exit 
routine from information passed by 
SORT. 

3. Calls the PL/I exit routine. 

Setting the return code in the PL/I exit 
program resets the parameters that IBMBKST 
passes to the SORT routines. 



Storage for SORT 



Storage for sort /merge workspace and the 
modules used is obtained in the LIFO stack. 
A VDA of the correct length is obtained by 
the bootstrap module. The length required 
must be specified in the arguments that are 
given in the call to PLISORT. These 
actions are summarized in figure 11,5. 



CHECKPOINT/RESTART 

The PL/I Optimizing Compiler allows the 
programmer to make use of the system 
checkpoint/restart facilities by calling 
the built-in subroutine PLICKPT. This is 
implemented by a call to the resident- 
library subroutine IBMBKCP, which issues 
the CHKPT macro instruction. 

Before the CHKPT macro instruction is 
issued, two control blocks must be set up. 
One of these control blocks contains the 
names of all tape files that are open; it 
is used to reposition the tapes on restart. 
The other control block contains 
verification information for all disk files 
that are open; it is used to verify that 
the disk packs are on the same devices on 
restart as they were when the check-point 
was taken. The two control blocks are held 
in workspace acquired by the module 
IBMBKCP- 

When a restart is made,, control is 
passed to the module IBMBKCP at a fixed 
entry point. After carrying out necessary 
checks, control is then returned to the 
calling routine in the normal manner. 
Control is thus returned to the statement 
after the call to PLICKPT, and processing 
continues . 



WAIT 



The PL/I WAIT statement allows the 
programmer to specify that processing shall 
halt until a specified number of events are 
complete. In the OS PL/I Optimizing 
Compiler, an event can be associated with 
either a record I/O operation or a DISPLAY 
statement, or it can be an inactive event 
that is not associated with any operation. 

All information relating to an event is 
kept in an eyent__variablej_ This is a 
control block of five words in length; it 
is treated for storage allocation like any 
other PL/I variable. The event variable 
holds information on whether the event is 
associated with an operation and whether it 
is complete; it also records the status of 
the event (i.e., whether the associated 
operation was completed successfully or 
otherwise) . When an event is associated 
with an operation, it is said to be ac tive; 
otherwise, it is said to be in active. 

When the wait statement is used, the 
keyword WAIT is followed by a list of 
events that are to be waited on. A number 
can follow this list, indicating that only 
that number of events need be completed 
before processing can continue. Typical 
WAIT statements are: 

WAIT (EVENT1,EVENT2) ; 

WAIT (EVENT1,EVENT2) (1); 

For the first statement, both the events 
would have to be completed before 
processing could continue. For the second 
statement, processing would continue as 
soon as either of the events was complete. 



Event Variables 



When storage is allocated for an event 
variable, the event variable is set 
inactive and incomplete. When the EVENT 
option is used to associate the event with 
an operation, the event variable is set 
active and incomplete. When a WAIT 
statement is executed and the operation 
associated with the event has been 
completed, the event variable is set 
inactive and complete. The status of the 
event is also set at this time, indicating 
whether or not the operation was 
successfully completed. 

The PL/I language allows the programmer 
to set complete or incomplete any event, by 
use of the COMPLETION pseudo- variable. 
This sets the appropriate bit in the event 
variable. The completion status may be 
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WAITER: PRGC OPTIONS (MAIN); 



ON TRANSMIT (A) CALL L; 
ON TRANSMIT (C) CALL L; 
ON TRANSMIT (X) CALL L; 





ON RECORD (A) CALL M; 




ON RECORD (C) CALL M; 




ON RECORD (X) CALL M; 




K=0; 


1 


READ FILE (A) INTO (B 




(El); 


2 


READ FILE (C) INTO ( 




(E2); 



EVENT 



(D) EVENT 



WAIT (E1,E2); 



IF K=l THEN WAIT (E2) ; 



5 BOOTLE: WAIT (E3); 



L: PROC; 

6 COMPLETION (E3)=»1'B; 

7 GO TO BOOTLE; 
END L; 

M: PROC; 

8 COMPLETION (E3)=*1'B; 

9 WAIT (E2); 

10 K=l; 

11 READ FILE(X) INTO(Y) EVENT 

(E2); 
END M; 

END WAITER; 



Figure 11.6. Example of WAIT 

implementation problems 



completed. If the number of events that 
have to be completed is not specified, all 
the events in the list must be completed. 
(For the multitasking situation, see 
chapter 14.) 

The WAIT makes use of the OS data- 
management WAIT macro instruction. 
However, because of the differences between 
the facilities offered by the OS and the 
PL/I language, considerable housekeeping 
problems are involved for waits on more 
than one event. For waits on single events, 
the problems are small and are described at 
the end of this section. 

When a WAIT or associated macro 
instruction is issued to the OS supervisor, 
the event is considered to be complete when 
input/output transmission is finished. In 
PL/I, however, a WAIT statement is not 
considered complete until any error- 
handling activity caused by the operation 
which was being waited on is finished. The 
error handling may include entry into an 
on-unit, and further WAIT statements may be 
executed in the on-unit. This process can 
continue to any number of levels of 
interrupt. 

PL/I also allows the programmer direct 
control over the completion of an event by 
use of the COMPLETION pseudo- variable, 
consequently, the PL/I programmer need not 
associate an event variable with an 
input/output operation, but can use it 
instead as a flag, setting the event 
complete at any point in the program. 

WAIT or associated macro instructions 
issued to the supervisor are completed by 
setting a completion bit in the ECB (event 
control block) which is held in the lOB. 
At the PL/I level, completion is indicated 
by setting the completion bit in the event 
variable. Thus a WAIT operation is carried 
on at two levels, the PL/I level and the 
system level. 



inspected by means of the COMPLETION built- 
in function. The PL/ I language also allows 
the programmer to inspect and change the 
status of an event, by means of the STATUS 
built-in function and pseudo- variable. 



WAIT Statement (Non-Multitasking) 



The WAIT statement in a non-multitasking 
environment is implemented by a call to the 
resident library routine IBMBJWT. IBMBJWT 
is passed a set of parameters consisting of 
the addresses of the event variables and 
the number of events that have to be 



ii2ysekeeping_Problems 



The problems involved in implementing the 
WAIT statement may be illustrated with 
examples from the skeleton program in 
figure 11.6. Four problems arise. They 
are: 

Problem_l: If an event being waited on in 
a multiple WAIT statement is completed in 
an on-unit entered while processing one of 
the other events in the statement, this 
must be made known to the first WAIT 
statement. Setting the event variable 
complete is not sufficient, because the 
event variable may be used again during the 
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on-unit. Suppose that the RECORD condition 
is raised during the execution of the WAIT 
statement numbered 3 in figure 11.6, for 
the operation associated with event El. 
The following then takes place: 

1. Control passes to procedure M. 

2, The statement WAIT(E2) is then 
encountered, and the program waits 
until event E2 is completed. When 
this occurs, the event variable is set 
complete and inactive. 



3. Event E2 is then used in a further I/O 
operation (statement 11), causing the 
event variable to be set active and 
incomplete. 

On return to the main program, there would 
be no way of determining from the event 
variable for E2 that the original event E2 
had been completed. The problem is solved 
by the use of control blocks called event 
tables (EVTABs). An EVTAB is set up by the 
wait module each time a WAIT statement is 
encountered; it contains entries for each 
incomplete event specified in the 
statement. The entries are termed EVTAB 
elements. Each element is chained to its 
corresponding event variable and contains a 
bit that can be set to indicate that the 
event has been completed, in the above 
example, therefore, EVTAB elements for El 
and E2 are set up when the wait module is 
called at statement 3, when the on-unit is 
entered, the WAIT statement 9 causes a 
further EVTAB to be set up with an entry 
for E2. The event variable pointer is reset 
to address the latest EVTAB elements, and a 
field in this element is set to point to 
the previous EVTAB element for E2. When 
event. e2 is completed (without causing any 
I/O conditions to be raised), the event 
variable and each EVTAB element for e2 is 
set complete and inactive, and a bit in the 
event variable is set to indicate that the 
chain of EVTAB elements is no longer 
associated with the event variable. When 
statement 11 is executed, the event 
variable is set active and incomplete. 
After the on-unit has been executed, the 
wait module sets the EVTAB element and 
event variable for El complete and 
inactive. It then tests any remaining 
EVTAB elements to determine whether they 
were set complete during an on-unit; in 
this case, it finds that the next EVTAB 
element (for E2) has been set complete and 
that there are no more events to process. 
Execution therefore continues until 
statement 4 is executed, at which time a 
new EVTAB element is created for E2 and 
chained to its event variable. 



Problem 2; A method must be provided to 
signal that an event waited on in an on- 
unit is already being waited on in the 
procedure that caused entry to the on-unit. 
suppose that the RECORD condition is 
encountered in the operation associated 
with E2 (statement number 2) during 
processing of the WAIT at statement number 
3. The following then takes place: 



control passes to procedure M. 



A further WAIT on E2 is encountered 
(statement number 9). Since E2 cannct 
now be completed, a mechanism must be 
available to raise the ERROR 
condition; otherwise, the program 
would never get out of the wait state. 



The problem is solved by setting a flag 
in the event variable whenever an on-unit 
is entered during WAIT statement 
processing. If the wait module is 
subsequently reentered from an on-unit, to 
process a WAIT on the same event, it finds 
that this bit is set and raises the ERROR 
condition. 

Problem.. 3: If there is a GOTO out of an 
on-unit, this involves setting an event 
variable complete,, and terminating the WAIT 
statement. Suppose the TRANSMIT condition 
is raised during the WAIT statement 
numbered 3, 4, or 9. The procedure L is 
entered and the following takes place: 

1. E3, which is a dummy event, is set 
complete. 

2. A GOTO is executed to the label 
BOOTLE . 

If no other action were taken, the event 
that caused entry to the on-unit (either El 
or E2) would not be set complete; any 
subsequent WAIT on that event would thus 
cause the wait module to be invoked, with 
unpredictable results. The problem is 
solved by setting a flag bit in the current 
DSA whenever the wait module is called. 
(The method is similar to that used to 
cater for a GOTO out of a SORT exit, and 
uses the same flag bit.) If the GOTO 
module finds that the bit is set, it 
returns to the wait module; the wait module 
sets the event variable complete and 
inactive and then returns to the GOTO 
module to continue the GOTO out of the on- 
unit. Only the event that caused entry to 
the on-unit is set complete. Any other 
incomplete events specified in the WAIT 
statement are left incomplete. 
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Figure 11.7. (Part 1 of 2). Summary of the wait statement 
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Figure 11.7. (part 2 of 2). Summary of the wait statement 
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Problem 4: If control reaches label BOOTLE 
without the TRANSMIT or RECORD condition 
having been raised, the event E3 can never 
be completed, some method must be 
available of making this fact known, 
otherwise the program would go into an 
indefinite wait on an event that could 
never be completed. This problem is solved 
by setting an event variable active only 
when it is associated with an operation. 
Thus, if a WAIT statement specifies an 
event that is inactive and incomplete, the 
wait module causes the program to be 
terminated. (If a WAIT statement specifies 
more than one event and one of the events 
is inactive and incomplete, the program is 
not terminated immediately because it is 
possible, although unlikely, that the 
incomplete event will be completed by the 
COMPLETION pseudovariable in an on-unit 
entered as a result of an I/O condition 
raised while processing one of the other 
events specified in the WAIT statement.) 



Control Blocks 



Four control blocks are involved in the 
implementation of the WAIT statement. 
These are shown in detail in appendix A. 

1* Even t va riable. Used to hold all 

information about the event at a PL/I 
level. Fields indicate whether it is 
active or inactive; complete or 
incomplete? whether it is already 
being waited on at a previous 
interrupt level; the type of operation 
with which it is associated. Each 
event variable- contains the address of 
its associated ECB or CCB and, if it 
associated with an I/O event, the 
address of the FCB for the file. 

2* IQg .X^yggt ..Go^^^o^ block) . Used to 
hold information about the event at 
the system level. For I/O events, ECBs 
are part of the lOB. For DISPLAY 
events, the equivalent control block 
is the display control block, which is 
set up by the display module. 

3* EVTAB (event table)^. Created for each 

entry to the WAIT module; comprises an 
element for every incomplete event 



that is to be waited on. The EVTAB is 
held in a VDA acquired by the WAIT 
module. 

^- ECB list. This is a list of ECB 
addresses that is created in 
circumstances that are explained 
below. The ECB list is held in the 
VDA described above, and acts as an 
argument list for the WAIT macro 
instruction. 



Wait Module (IBMBJWT) 



The actions of the wait module, IBMBJWT, 
are shown in the flowchart in figure 11.7, 
and are described in detail in the 
publication OS_PL/I_Resident Library 
Program _Lggic . 

As the flowchart shows, the WAIT module 
sometimes issues a WAIT macro instruction, 
and sometimes relies on the CHECK macro 
instructions in the PL/I transmitters. The 
reasons for this are as follows. 

The CHECK macro instruction in the 
transmitter can only be used for I/O 
events, and only one transmitter can be 
called at a time. If only a certain number 
of the events in an event list need to be 
completed, it is uneconomic to pass these 
events one at a time to the transmitter, 
because the first event passed could be the 
last to finish, consequently, whenever non- 
I/O events are involved and whenever less 
than the total number of events in an event 
list have to be completed, an ECB list is 
generated for all incomplete events and a 
WAIT macro instruction is issued. 

The WAIT macro instruction returns 
control as soon as any event in the list is 
complete, thus allowing an event list to be 
handled efficiently when only a number of 
events have to be completed. For I/O 
events, it is still necessary to issue the 
CHECK macro instruction in the transmitter, 
even though the events are known to be 
complete. This is because the CHECK macro 
instruction carries out various checking 
functions as well as waiting until the 
event is complete. 
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( ^'"' ) 




No 



Read section 1 of this chapter to discover correct 
method. (Use of SYSABEND or SYSUDUMP will 
not necessarily produce a dump) 



Yes 




Ng ^ 



Do not attempt to debug without this knowledge. Read 
chapter 1 and introduction to chapters 6 and 7 of this 
book. 



Yes 




Yes 



Examine contents list at start of section 3 to find 
quickest method of finding item. 



No 




Yes 



Use contents list at start of section 3 to simplify finding 
various items. 



Follow the most suitable check list in 
section 2 of this chapter. Refer to 
keyed items in section 3 for details. 



Figure 12.1. How r.o use this chapter when debugging 
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Chapter 12: Debugging using Dumps 



The OS PL/I Optimizing Compiler allows the 
programmer to obtain an execution time dump 
only by calling PLIDUMP. Using SYSABEND or 
SYSUDUMP in the JCL will not result in a 
dump after a program interrupt or, except 
in certain exceptional cases, after an 
ABEND. This is because the program 
interrupt exit and the task asynchronous 
exit are reset by issuing SPIE and STAE 
macro instructions in the program 
initialization routine. These SPIE and 
STAE routines result in all interrupts, and 
the majority of ABENDS, being passed to the 
PL/I error handler. 



Certain types of program error can, 
however, result in overwriting of the 
control information used by the error 
handling routines. When this occurs an 
ABEND will be issued that results in system 
action. This ABEND has a user code of 4000. 
Provided that a SYSABEND or SYSUDUMP DD 
card was included in the JCL an ABEND dump 
will then be generated. 

ABEND dumps are issued in three 
circumstances. 

1. When an interrupt occurs during the 
execution of one of the error handling 
routines. 

2. when housekeeping control blocks have 
been overwritten after an ABEND in the 
program. 

3. If the NOSPIE or NOSTAE option has 
been used, and the action inherited by 
the PL/I program is to give a dump. 

The first two of these situations are most 
probably caused by overwriting of control 
information by the PL/I program. The first 
can be identified because a message is sent 
to the console that reads 'Interrupt in 
error handling routines program 
terminated* , and the ABEND code will be 
4000. 

Chapter 7, 'Error Handling' describes 
the methods used to handle interrupts and 
ABENDS. It also describes the 
implementation of PLIDUMP. This chapter is 
concerned solely with debugging using the 
facilities provided. 

It is always possible for the programmer 
to ask an operator to take a stand-alone 
dump at any point in the program. The need 
to do this should, however, occur only 
infrequently. 



How to use_this _Chapter 



This chapter contains information on how to 
obtain and interpret dumps, and on how to 
identify compiled code, data, and control 
blocks within a dump. Some knowledge of 
the compiler's housekeeping scheme, 
described in other chapters of this book, 
is ass\amed. Trying to use a dump without 
this knowledge can result in a great deal 
of wasted time. To acquire a quick overall 
picture, chapter 1 and the introduction to 
chapters 6 and 7 should be read. A summary 
of how to use this chapter when debugging 
is given in figure 12.1. 

This chapter is divided into four 
sections: 

Section 1: How to obtain a PL/I dump 

Section 2: Recommended debugging 
procedures 

Section 3: Locating specific 
information 

Section 4: Special considerations for 
multitasking 

Section 1 explains how to obtain a 
hexadecimal dump of a PL/I program. It 
also gives some suggestions on the use. of 
various compiler and PL/I options that may 
prove useful when debugging. 

Section 2 offers two recommended courses 
for debugging a PL/I program by use of a 
dump. The first course deals with a PL/I 
dump that has been called from an ERROR on- 
uhit and is being used to debug the probleir 
program. The second course deals with the 
situation in which an OS system dump has 
been generated, probably because the 
housekeeping control blocks have been 
overwritten. 

Section 3 describes how to find various 
data areas and other information. It is 
indexed and numbered for quick reference. 

Section 4 describes the special 
considerations that must be taken into 
account when debugging a program that uses 
multitasking . 

Before taking a dump. Section 1 should 
be read, because the methods used are not 
those familiar to programmers using OS. 
Sections 2 and 3 are for use when 
debugging. Programmers who know what they 
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•PROCESS LIST MAP GOSTMT FLOW (n,m); 

' (SIZE, SUBSCRIPTRANGE, STRINGRANGE): 
DUMPER: PROC; 
ON ERROR CALL PLIDUMP ('HB', 'ERROR ON-UNIT DUMP' 



END; 



'■ ® 



® These options give compiled code listing and 
static storage map, essential for interpreting 



® 



any dump. 

Provides trace of last n branch-out/branch-in 
points in up to m blocks if SNAP or PLIDUMP 
with trace is used. MAP results in the generation 
of a table showing offsets of static and automatic 
variables from their defining bases. 



©Permits trace of statement numbers in original 
source program, and simplifies program checking. 



® Prefix options. The use of these PL/I checkout 
options is strongly urged. Since, however, they 
cause an increase both in the size of object code 
and in execution time, it may be necessary to 
restrict their use to suspected blocks or statements. 



®Two arguments can be passed to PLIDUMP. 
They are the dump options character string and 
the dump identifier. The format of the call 
statement is: 



I 
CALL PLIDUMP (character-string-expression 1, character-string-expression 2); 



Dump options character string 
(Default is 'TFC') 



T Trace information required 

NT No trace information required 

F File information required 

NF No file information required 

S Stop after dump 

C Continue after dump 

H Hexadecimal information required 

NH No hexadecimal information required 

B Control block information required 

NB No control block information required 

A Dump all tasks 

O Dump current task only 

E Exit from task after dump 



Dump identifier character string 



Printed at head of dump. May be up to 90 
characters long. 



Figure 12.2. Code for debugging 
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are looking for should refer directly to 
the contents table in section 3. This will 
direct them to numbered sections which give 
details of how to find particular items. 
Programmers who have no preferred scheme of 
their own can follow the recommended 
procedures in section 2. Section 2 
crossrefers to the items in section 3, so 
that the details of the steps involved may 
be quickly found. 



Section 1: How to Obtain a PL/I Dump 



In order to get a formatted PL/ I dump, the 
programmer must include a call to PLIDUMP 
in his program. 



CALL PLIDUMP 



The statement CALL PLIDUMP may appear 
wherever a CALL statement may legitimately 
be used. It has the following form: 

CALL PLIDUMP 

(character-string-expression 1, 
character- string- expression 2) ; 

Character-string-expression 1 is a "dump 
options" character string consisting of one 
or more of the following dump option 
characters: 

T Trace. A calling trace through all 

active DSAs is generated. When an on- 
unit DSA is encountered, the values of 
the relevant condition built-in 
functions are given. The reason for 
the entry to the on- unit is also given 
if the ERROR or FINISH conditions are 
raised as standard system action for 
another condition. 



NT No trace, 
given.. 



A calling trace is not 



F File information. A complete set of 
attributes for all open files is 
given, plus the contents of all 
accessible buffers. 

NF No file information required. 

S Stop. The program will be terminated 
after the dump, 

C Continue. Execution of the program 
will be continued after the dump. 

H Hexadecimal. A SNAP hexadecimal dump 
of the partition will be given. If 
trace information is requested, the 
TCA and DSA addresses will be given. 



If file information is requested, the 
addresses of the FCBs will be given 
and the contents of all accessible 
buffers will be printed in hexadecimal 
notation as well as in character. 

NH No hexadecimal dump required. 

B Blocks. The contents of the TCA, TIA, 
DSAs, FCBs, and file buffers are 
printed in hexadecimal notation. 

NE No block information required. 

Tasking . Options 

A All 

All results in a dump of all active 
tasks including the control task - see 
chapter 14. 

O Only 

Only results in a dump of the current 
task and a dump of the control task. 

E Exit 

Exit results in the termination of the 
task after the dump. 

The default options are TFCANHNB. That 
is, trace information, file information, no 
block information, no hexadecimal dump, all 
tasks,, and continuation after the 
information has been put out. 

Options are read from left to right. 
Invalid options are ignored, and if 
contradictory options are coded, the 
rightmost options are taken. 

Character-string-expression 2 is a "user 
identifier" character string of up to 90 
characters chosen by the PL/I programmer. 
It is printed at the head of the dump. If 
the character string is omitted, nothing is 
printed. 

If PLIDUMP is called a number of times 
in a program a different user identifier 
should be used on each occassion. This 
will simplify identification of the point 
at which the dump was called. 



RECOMMENDED CODING 



For PLIDUMP to produce a dump, a DD card 
for PLIDUMP must be included in the JCL. 
PLIDUMP can be called from anywhere in a 
program, but the normal method used when 
debugging will be to call PLIDUMP from an 
on-unit. As 'continuation after the dump is 
one of the options available, PLIDUMP can 
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be used as a snap dump to get a series of 
dumps of main storage throughout the 
running of the program. 

By including the statement CALL PLIDUMP 
(•HB',*dump identifier'); in an ERROR on- 
unit, it is possible to obtain a 
hexadecimal dump,, with control blocks 
identified and formatted, should an error 
occur. If an ERROR on- unit is being 
included in a program, care should be taken 
that there are no further ON ERROR 
statements which might override the on-unit 
requesting a dump. 

Suggested code for use when debugging 
with a dump is given in figure 12.2. 



AVOIDING RE-COMPILATION 



If an ERROR on-unit containing a call to 
PLIDUMP is to be included in an existing 
program,, it is necessary to re-compile the 
program. This course is advisable as it 
allows other diagnostic aids, such as 
SUBSCRIPTRANGE,, to be included. However, 
if re-compilation is not desirable, a PL/I 
dump can be obtained by using a small 
bootstrap routine that contains an ERROR 
on-unit calling PLIDUMP. This routine can 
be compiled and then link- edited with the 
object module of the program that needs to 
be dumped. The on-unit will then be 
inherited by the program that requires a 
dump, and a dump will be generated when an 
error occurs. A suitable bootstrap program 
is shown in figure 12.3. When using this 
method, the bootstrap must be link-edited 
as the MAIN procedure; it should therefore 
be passed to the linkage editor before the 
program that requires dumping, since that 
program will also have the MAIN option. If 
the program that requires dumping expects 
to be passed parameters, the bootstrap 
procedure should use an identical parameter 
list in its PROCEDURE statement, and should 
include an identical argument list in the 
CALL statement used to invoke the inner 
procedure . 

If the program that requires dumping 
already has an ERROR on-unit, this will 
override the ERROR on-unit in the bootstrap 
program- 
In certain circumstances, a dump can 
still be obtained. 

1. If the reason for the entry to the on- 
unit is the occurence of a PL/I 
condition an on-unit for this 
condition in^the bootstrap program 
will result in a dump being taken 
before the ERROR on-unit is executed. 



(For example, if the CONVERSION 
condition was occurring in the program 
to be dumped a CONVERSION on-unit 
could be included in the bootstrap 
program. Such an on-unit would be 
entered before the ERROR condition was 
raised. ) 

2. Provided that the ERROR on-unit does 
not include a GOTO out of the on-unit, 
a FINISH on-unit can be used. Since 
the standard system action for the 
ERROR condition is to raise the FINISH 
condition, the dump will be generated 
after the ERROR on-unit has been 
executed. 

There is no point in including 
SUBSCRIPTRANGE or Other prefixes in the 
bootstrap routine, because these are not 
inherited by called programs. 

The bootstrap method is not recommended 
unless there are particularly strong 
reasons for avoiding re-compilation. 



BOOTSTRAP: PROC OPTIONS (MAIN); 

DCL program* ENTRY EXTERNAL; 

ON ERROR CALL PLIDUMP ('HB', 
•BOOTSTRAP*) ; 

CALL program*; 

END; 
*The name of the program to be dumped 
should be inserted at the points marked 
program* in this example. 



Figure 12.3. suggested method of 

obtaining a dump when re-compilation 
is particularly undesirable. (See 
text before using this method. ) 



CONTENTS OF A PL/I DUMP 



The appearance of a typical dump produced 
by the PLIDUMP modules with the options 
TFHBA is shown in figure 12.4. The 
contents of particular sections are 
described in detail below. 



Headings 

The dump is headed by the line 
***PL/I DUMP*** 
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* * * PL/I DUMP ♦ ♦ ♦ 



USER IDENTIFIER 



KXAMPLE OP PLIDOMP 



♦ ♦ * CALLIN(J TRACE ♦ ♦ ♦ 

(TCA ADDRESS O3D8O0 ) 

PLIDUMP WAS CALLED FROM STATEMENT NUMBER 3 AT OFFSET +00009E FROM A ERR TYPE ON-UNIT WITH ENTRY ADDRESS 03A51C 
(AND DSA ADDRESS 03E050 ) 

ERROR DIAGNOSTICS 

PL/I CONDITION DETECTED: CONV 

ONCODE = 612 SEE LANGUAGE REFERENCE MANUAL 

ONCHAR =1 CHARACTER CAUSING CONVERSION ERROR 

ONSOURCE =IF THIS DOES NOT RAISE CONVERSION NOTHING WILL 

STRING CAUSING CONVERSION ERROR 

ADDRESS OF ERROR HANDLER'S SAVE AREA 03DE50 

REGISTERS ON ENTRY TO ERROR HANDLER 



REGS 0-7 FF03DE50 
REGS 8-15 00000001 



OOOaDEtB 
0003DD55 



0003DDD0 
00000000 



6E03C'tC6 
0003B9CE 



0003DBF8 
0003D800 



0003DD28 
FF03DDF8 



0003DDE0 
1JE03C6A8 



8003A37A 
0003BD52 



END OF ERROR DIAGNOSTICS 

WHICH WAS CALLED FROM A LIBRARY MODULE WITH ENTRY ADDRESS 03C4C0 (AND DSA ADDRESS 03DDF8 ) 

WHICH WAS CALLED FROM A LIBRARY MODULE WITH ENTRY ADDRESS 03B770 (AND DSA ADDRESS 03DAE8 ) 

WHICH WAS CALLED FROM A LIBRARY MODULE WITH F.NTRY ADDRESS 03A5D0 (AND DSA ADDRESS 03DD80 ) 

WHICH WAS CALLED FROM STATEMENT NUMBER 5 AT OFFSET ♦OOOOAC FROM PROCEDURE EXAMPLE WITH ENTRY ADDRESS 03A160 
(AND DSA ADDRESS 03DC68 ) 

♦ • ♦ END OF CALLING TRACE * * * 

TRACE OF PL/I CONTROL BLOCKS 



TASK COMMUNICATIONS AREA 



ADDR. 


OFFSET 










03D800 


00000 


00000000 


0003DC58 


FF03D800 


FF0it8A20 


03D820 


00020 


00000000 


0003DAU8 


0003D920 


Di»D9Ci»Cl 


03D840 


oooto 


0003D9EO 


00000000 


0003CCAE 


00000000 


03D860 


00060 


0003B4 8C 


0003B638 


100AIJ7P0 


0003CCA0 


03D880 


00080 


582E000« 


58EE0000 


19DFU78C 


00C29500 


03D8A0 


OOOAO 


07FF0000 


00000000 


000007FE 


0003B1(EA 


03D8C0 


OOOCO 


D0209160 


D001078E 


911I0D001 


U78C00DC 


03D8E0 


OOOEO 


D05U9180 


D05a071E 


181F58FC 


OOF407FF 


03D900 


00100 


0003D8AA 


0003D8AA 


00000000 


00000000 



00000000 0003D810 0005U7B0 0003D9C0 C C R- 

0003DA50 00000000 0003DA18 95D9C02'* R.MRDA R.. 

00000000 00000000 80000000 0003BU8A ..R 

0003CCA2 0003CCB2 0003BD52 lOOClOOO .0 

C00m78C 00BC180E 18E1181F 58FC00AC 

AUEC58FC 0078051F DB01A166 18DF9831J 

D203D0UC D0509120 D001078E D201D056 -..-.... 

17225D20 00000000 0003D8AA 0003D8AA U . . . . ) Q...Q. 

00000000 00000000 00000000 2000U323 ..Q...Q 



.B. 



.K. 



TCA IMPLEMENTATION APPENDAGE 



ADDR. OFFSET 
03D920 00000 00049000 00000000 0E03BD18 7FFD1030 
03D940 00020 0003D9F8 0003DA98 0003B5A2 00000000 



00000000 00000000 00000000 00000000 
00000000 00000000 00000000 00000000 



♦ * * PL/I DUMP ♦ ♦ * 



03D960 OOOUO 0003B5F8 0003C30C 

LIBRARY WORK SPACE 

CONTENTS OF REGISTER SAVE AREA 

REGS 0-7 0003D198 0003A39C 
REGS 8-15 0003E100 0003E120 



0003E050 
0003DC68 



UE03B386 
0003D920 



0003DBF8 
D2008003 



00000000 
FF03DEE8 



0003A39C 
4E03B3B6 



0003A400 
8E03D19C 



ADDR. OFFSET 
03DEE8 00000 
03DF08 00020 
03DF28 00040 
03DF48 00060 
03DF68 00080 



08000110 0003E050 9C188000 4E03B3B6 
4E03B386 0003OBF8 00000000 0003A39C 
0003D920 D2008003 0003DF70 FF03E128 
P0F0F3F2 F1F245F0 00000000 0000005C 
40404040 40404040 



8E03D19C 0003D198 0003A39C 0003E050 + J. ..J., 

0003A400 0003E100 0003E120 0003DC68 ♦ 8 , 

70020080 0003DF60 00440000 00100002 ..R.K -. 

4E049AFC F0C1C35C 40404040 40404040 003212.0 ♦>...OAC* 



DYNAMIC SAVE AREA (ON-UNIT) 

CONTENTS OF REGISTER SAVE AREA 

REGS 0-7 FF03E128 0003A39C 
REGS 8-15 0003E100 0003E120 



5E03A572 
0003DC68 



0003A308 
0003D920 



0003DBF8 
7098C030 



00000000 
0003E050 



01003DD10 
4E03A5BA 



0003A400 
0003B380 



ADDR. 


OFFSET 


03E050 


00000 


03E070 


00020 


03E090 


00040 


03E0B0 


00060 


03E0D0 


00080 


03E0F0 


OOOAO 


03E110 


OOOCO 



8C24E090 FF03DE50 050CB000 4E03A5BA 0003B380 FF03E128 0003A39C 5E03A572 ♦. 

0003A308 0003DBF8 00000000 0003DD10 
0003D920 7098C030 FF03DEE8 FF03E128 
D2031020 9BKE41F0 000442F0 100858FO 
802445E0 96E2D203 0003E090 D2039BD6 
9BC650F0 9BDA5880 709858F0 802054F0 
C1D4D7D3 C540D6C6 40D7D3C9 C4E4D4D7 



0003A400 0003E100 0003E120 0003DC68 8 

FF03E128 91E091E0 0003DC68 50F09BEA ..R Y 0.. 

9BAE07FF 58809BE6 D2039BE6 709858F0 K 0...0...0 WK..W...0 

70D858F0 802043P0 B00P50F0 B00C54F0 SK K. .O.Q.O. . .0. . . 0. . .0 

E3C6C2C8 0003E100 00040000 OO00C5E7 .F.0 0...0TFBH EX 

0003E10E 00120000 AMPLE OF PLIDUMP Y 



Figure 12.4. An example of PLIDUMP 
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j Abbreviation 


Condition Name 


1 AREA 


AREA 


1 CHCK 


CHECK 


1 COND 


CONDITION (pro 




named condit 


1 CONV 


CONVERSION 


1 ENDF 


ENDFILE 


1 ENDP 


ENDPAGE 


1 ERR 


ERROR 


1 FIN 


FINISH 


1 FOFL 


FIXEDOVERFLOW 


1 KEY 


KEY 


i NAME 


NAME 


1 OFL 


OVERFLOW 


1 REC 


RECORD 


1 SIZE 


SIZE 


1 STRG 


STRINGRANGE 


1 STRZ 


STRINGSIZE 


1 SUBG 


SUBSCRIPTRANGE 


1 TMIT 


TRANSMIT 


1 UFL 


UNDERFLOW 


1 UNDF 


UNDEFINEDFILE 


j ZDIV 


ZERODIVIDE 



Figure 12.5. Abbreviations for 

condition names used in PLIDUMP 
trace information. 



This is followed by the user identifier, if 
any, given as the second character string 
in the argument list of PLIDUMP. 



Trace Information 



A request for trace information results in 
the following output: 

1. A trace of every procedure, begin 

block, and on-unit that is active at 
the time of the call to PLIDUMP. For 



procedures, the procedure name and 
statement number from which the 
procedure was called are given. If 
the *H' option is requested, the 
offset of the statement is given as 
well as the entry point address and 
DSA address. Also, if the entry point 
used is not the main entry point and 
the statement number option was 
specified, the main entry name is 
given. 



For multitasking programs the name of 
the task variable, its status, and the 
absolute priority of the task are 
printed. If no task variable is 
supplied "NONE" is printed as the name 
of the task variable. A dummy task 
variable will have been supplied see 
chapter 14. 



2. For on- units, the values of any 

relevant condition built-in functions 
are given. The type of on-unit is 
given and, where the cause of entry 
into the on-unit is not self- 
explanatory, the cause of entry is 
also given (e.g., if an ERROR on-unit 
was entered because of a conversion 
error, this fact is given in the trace 
information) . The on-unit type is 
specified, using a three or four 
letter abbreviation. A list of these 
abbreviations is given in figure 12.5. 



3. When a hexadecimal dump is requested, 
the entry point address of each active 
block is also given,, together with the 
address of its associated DSA. 

4. When the compiler FLOW option is in 
effect, the flow statement table is 
given. 

5. If a hexadecimal dump is requested, 
the address of the TCA is printed at 
the head of the trace. 

6. If either a hexadecimal dump or 
control block information has been 
requested, and any ERROR on-units are 
traced, then the following information 
is also included: 

a. The address of IBMBERR's DSA. 

b. The contents of the general and 
floating point registers at the 
time IBMBERR was called. 

c. If there was an interrupt, the 
address of the interrupt. 

d. A trace of library DSAs back to 
the last compiled code DSA. 
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BYTE 1 PL/I condition if any 


BASE_Ng^. 


BYTE 1 PL/I condition if any 




X'02» 


ZERODIVIDE 


320 


X'CD' 


9250 


X*03* 


FIXEDOVERFLOW 


310 


X'CF' 


1000 


X'04' 


SIZE 


340 






X'05« 


CONVERSION 


600 


X*D3» 


9200 


X*06« 


OVERFLOW 


300 


X»D5' 


3500 


X'07* 


UNDERFLOW 


330 


X*D7» 


4050 


X'08' 


STRINGSIZE 


150 


X«D9* 


5050 


X'09« 


STRINGRANGE 


350 






X'OA' 


SUBSCRIPTRANGE 


520 






X'OB» 


AREA 


360 


X'DF' 


5000 


X«OC« 


ERROR 


009 


X'El' 


9050 


X'OD* 


FINISH 


004 


X'E3' 


1000 


X*OE« 


CHECK 


510 


X'E5' 


4000 


X'OF' 


CONDITION 


500 


X'E7' 


xxxx 


X'lO' 


KEY 


050 


X'E9' 


4050 


X'll' 


RECORD 


020 


X'EB* 


0003 


X'12« 


UNDEFINEBFILE 


080 


X'ED* 


1000 


X*13« 


ENDFILE 


070 


X'EF' 


1550 


X'lH* 


TRANSMIT 


040 


X'Fl' 


1500 


X'15« 


NAME 


010 


X'F3' 


2000 


X«16» 


ENDPAGE 


090 


X'F5' 


3768 


X'17' 




- 


X'F7' 


3000 


X»18* 






X'F9« 
X«FB' 
X'FD* 
X*FF« 


3800 
3900 
9000 
8090 


Note: 


Meanings are only given where 


there is a 


directly associated PL/I condition. 





Figure 12.6. Error code field lookup table 



File Information 



A request for file information results in 
the following output: 

1. The default and declared attributes of 
all open files are given. 



2. Buffer contents of all buffers are 
given. If a hexadecimal dump has been 
requested, the contents of the buffers 
are given in both hexadecimal and 
character notation. If no hexadecimal 
dump is requested, the contents are 
given in character notation only. 

3. The contents of the FCBs, DCBs, 
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DCLCBs, lOCBs, and exclusive file 
blocks are given in formatted 
hexadecimal notation, if either the 
'H* or 'B* option is also included. 



Hexadecii(nal_DumE 



The hexadecimal dump is produced by the 
execution of a SNAP macro instruction. 
Thus the normal SNAP dump is produced. 
This is fully described in the Programmers 
Guide to Debugging . 

It should be noted that the PSW will 
contain the address of an instruction in 
IBMBKMR,, one of the modules used to 
implement PLIDUMP. This will bear no 
relation to the error in the dumped 
program . 

If the program is not multitasking the 
SNAP macro specifies all register save 
areas, subpools, task control blocks, and, 
provided the O (Only) option is not 
included in the PLIDUMP options, the trace 
table. 

For a dump of a multitasking program the 
contents are: 

In the control task 

Register save areas 
Subpools 

Trace table 

Control blocks 

In the other tasks 

Register contents 
Register save areas 

Subpools 

Jobpack Area 

Linkpack area 



block, first in hexadecimal and then in 
character notation. For DSAs, the type of 
DSA is shown; i.e., library DSA, procedure 
DSA, on-unit DSA, or dummy DSA. The 
contents of the FCBs, DCLCBs and lOCBs for 
any open files are printed in a similar 
format. 

In a dump of a multitasking program the 
contents of the tasking appendage is also 
printed. 

If the option A (all) is used in a 
multitasking programming the TCA, TIA, DSAs 
and tasking appendage of all directly 
ascending tasks will be printed. FCBs, 
lOCBs, DCLCBs will be printed after files 
open in any task if the option A is used. 



Section 2: Recommended Debugging 
Procedures 



The main difficulty in reading a dump of a 
PL/I program is knowing where to start. 
The signposts known to assembler language 
programmers are of little help. There are, 
however, five main sources of information 
to be considered when using a dump to debug 
a PL/I program. They are: 

1. The statement number and the address 
where the error occurred (if the dump 
was taken after an error) 

2. The type of error (if the dump was 
taken after an error) 

3. The values in the general registers 
when the dump was taken or when the 
error occurred 

U. The chain of DSAs 

5. The TCA 



Block Option 



When the block option is used, the contents 
of the TCA, the TIA (TCA appendage) , and 
the DSAs in the LIFO stack (that is, all 
active DSAs) are printed in hexadecimal and 
character format. The absolute address is 
printed in the left hand column; the 
offsets within the block are then printed. 
This is followed by the contents of the 



The first two of these items hold 
equivalent information to that held in the 
PSW in an OS system dump. The last three 
items enable the housekeeping to be checked 
and the location of the control blocks and 
the program variables to be discovered. 
The methods of locating other information, 
given in section 3, refer to the key areas 
shown above. 

Note: Meanings are only given where there 
is a directly associated PL/I condition. 
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Software detected interrupt 

DSA of block in which 
interrupt occurred 



Program check interrupt 

DSA of block in which 
interrupt occurred 



1 ► 


4 

8 
44 


4 




Backchain 


Registers 14 through! 1 at time of interrupt 


Other DSA information 


DSAforlBMBERR 




Backchain, register save area, address 
of LWS, NAB, etc. 








50 


Qualifier for I/O, CHECK condition 


54 


1 St 2 bytes of error 
code passed to 

IBMBERR 








5C 


Not used 


84 





1 ► 



4 

8 

C 

14 

44 


4 




Backchain 




Interrupt address from word 2 of PSW 




Registers through 1 1 at time of interrupt 


Other DSA information 


DSAforlBMBERR 




Address of interrupt DSA 






1 


8 


Register save area, address of LWS, NAB, etc. 


54 


Error code created 
by IBMBERR 




58 




Interrupt code 


5C, 


Register 14 at time of interrupt 


60 


Register 15 at time of interrupt 






68 


Floating point registers 0, 2, 4, 6 
/ 



Floating point registers are saved only if interrupt 
relates directly to a PL/I condition, and return may 
be made to the point of interrupt 

Figure 12.7. The contents of IBMBERR 's DSA after a system detected and a PL/I 
interrupt 
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To previous DSA 



Flags 



Reserved 



Backchain 



Not used 



Register save area (60 bytes) 



48 



4C 



50 



R13 



Address of library workspace 



Segment No. 



Segment No. 



NAB 



End of prologue NAB 



Space for automatic variables and temporaries. 
Length depends on number and type of 
variables declared in the associated block. 



Flags 



Reserved 



Backchain 



NAB points to the 
next DSA only if it 
is in LIFO storage 
and has the same 
segment number 



Current 
DSA 



Figure 12.8. The chaining of DSAs 
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When debugging, it is essential to have 
a listing of the object program, a 
variables offset map and a linkage editor 
map. The object program listing allows the 
programmer to study the instructions that 
are being carried out and to find various 
control blocks in static storage. The 
linkage editor map allows the programmer to 
identify particular parts of the executable 
program phase and, to identify the routine 
associated with each DSA. 

Note: The PSW in the SNAP dump should not 
be consulted. This will give the address 
at which the SNAP macro instruction was 
issued. This is an address in one of the 
PLIDUMP modules and is not relevant to the 
error in the problem program. 



DEBUGGING PROCEDURES 



The best approach to a dump depends on the 
problem to be solved and must therefore be 
left largely in the hands of the 
programmer. However, two suggested courses 
of action are given in this section. 

These courses cover two situations: 

1. When PLIDUMP has been called from an 
ERROR or other on-unit 

2. When only an OS ABEND dump has been 
generated. 

Other possible situations are when a 
dump is taken at a specified point in the 
program,, or when a stand-alone dump is 
taken. No attempt is made to suggest a 
course of action in these circumstances. 
However, in such cases, the main storage 
situation can be investigated by following 
the methods itemized in section 3 of this 
chapter. 

Throughout each of the two recommended 
procedures given in the following 
paragraphs, there are cross-references to 
the methods given in section 3. The cross- 
references consist of the keys by which the 
methods are identified; for example, H6, 
D5. 



gi'^I-Dyg!B..Qg3;3:g^.„.l£2S!,.,.Ql^~:ygJ:t;: 



If a PL/I dump is called from an ERROR on- 
unit it can be assumed that the 
housekeeping system of the program is 
working. If it were not working, the dump 
would probably not have been generated. 

A large amount of diagnostic information 



will be available at the head of the duirp. 
An error message will have been generated, 
and this will provide a useful starting 
point. The first step should be to examine 
the type of error and the point at which it 
occurred. ONCODE and other condition 
built-in function values should be 
examined, as should the trace information. 
A suggested procedure is the following: 

1. Examine the error by means of the 
ONCODE and any other relevant built-in 
function values. These values are 
given in the trace information. (The 
meanings of encodes are given in the 
Language Reference manual for this 
compiler. ) 

2. Find the location of error (PI) and in 
which block the error occurred (H12) . 
If error occurred in library module, 
see HIU. This information is norirally 
available from the head of the 
PLIDUMP. 

3. Examine the trace to see if it appears 
as expected. 

4. Examine the information in the file 
buffers, and check that file 
attributes are as expected. This 
information will be printed in the 
dump heading. 

5. Check the values of any variables 
involved in the interrupt (V1-V6). 

6. Check values of registers to see if 
dedicated registers are pointing to 
correct areas (H8 6 H9) . Distinguish 
between compiled code and library 
register usage. 

7. If SUBSCRIPTRANGE or STRINGRANGE is 
not enabled, check that the error was 
not caused by one of these conditions. 

8. Check housekeeping (H1-H16) starting 
with area most directly concerned with 
type of statement in which the error 
occurred. 

9. Check values of all variables in the 
program (V1-V6) . 

10. Check logic of code being executed 
from object listing. 



0§_ABEND__Dum2 



Provided a SYSABEND or a SYSUDUMP card is 
included in the JCL an OS ABEND dump will 
be generated when there is a failure of the 
error-handling modules, or of the module 
that prints the PL/I hexadecimal dump. It 
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should be noted that the failure of these 
modules is more likely to be caused by the 
overwriting of essential information than 
by an error in the modules themselves. 

Because ABENDS caused by overrunning the 
specified time (SYSTEM 322) do not enter 
the STAE exit, these will cause dumps to be 
generated in normal circumstances. 

An ABEND dump will not normally be 
produced for program checks, because a 
program check exit is set by the PL/I 
housekeeping routines, so that the system 
returns all program checks to the error 
handler. In the error handler itself, the 
program check exit is reset so that a 
program check interrupt will result in a 
dump. 

Thus,, an ABEND will be produced if the 
program interrupt exit, which is normally 
set by the program initialization routines 
to prevent a dump, has been reset during 
the program,, or, possibly, has not been set 
at all. The second alternative is extremely 
unlikely. A third possibility is that the 
program check exit itself is not working, 
and the SPIE macro in the initialization 
routines did not successfully set the 
program check exit. The most probable of 
these suggested causes is that the program 
check exit has been reset by the program. 
The program interrupt exit is always reset 
for the duration of error handling or 
PLIDUMP, to prevent looping should an 
interrupt occur. (see chapter 7, "Error 
Handling. ") if an interrupt occurs during 
error handling, an ABEND with a code of 
UOOO is produced. This will result in a 
dump if SYSABEND or SYSUDUMP cards have 
been provided. An interrupt in the error- 
handling routines indicates either that the 
error-handling routines are at fault, or, 
more probably, that some of the control 
information of the error-handling routines 
has been overwritten during the execution 
of the program. The most practical 
solution may be to re-run the program with 
SUBSCRIPIRANGE, STRINGSIZE, and STRINGRANGE 
enabled. 

These PL/I conditions check for possible 
overwriting by subscripts or substrings 
that are beyond the bounds of the variable 
referred to. 

However, having obtained an ABEND dump, 
the following debugging procedure may be 
adopted. 

1. Determine whether the dump was caused 
by an interrupt in the error handling 
routines or a housekeeping error 
discovered during the analysis of an 
ABEND. If the cause was an interrupt 
in the error handler a message will 
have been sent to the console before 



the ABEND was issued, and the ABEND 
will have a code of 4000, if the 
interrupt occurred in one of the error 
handling routines. Note that codes 
322 and 122 may also give system 
dumps. And that the use of NOSPIE or 
NOSTAE can result in the generation of 
a dump. 

2. Locate instruction causing interrupt. 
This is done by looking for the PSW 
(01). 

3. Inspect this instruction to see if it 
appears to have teen overwritten, 
bearing in mind the cause of the 
interrupt, e.g., 

a. do the registers used in the 
instruction contain incorrect 
information, picked up because of 
overwriting? 

b. is it a branch to a protected 
address? 

4. Inspect the TCA(05) to ensure that all 
error-handling addresses are correct. 

5. Investigate the housekeeping fields, 
starting with the DSA chain (H1-H3), 
then the chain of ONCAs (H5,H6). 

6. Investigate the error that caused 
entry into the error handler. This 
can be done by examining the contents 
of IBMBERR's DSA (H7) and the 
associated ONCA (H6) . See whether 
incorrect information passed to the 
error handler could be causing a 
failure. 

7. Check for uninitialized variables 
(particularly pointers), and incorrect 
passing of parameters. 

8. If none of the above produces a 
solution, an error in the error- 
handling modules is a possibility. If 
you decide to call IBM for assistance 
at this point,, refer to appendix C in 
the Programmer's Guide for this 
compiler. The cause of the original 
entry to the error handler may have 
been discovered, and can,, perhaps, be 
avoided by altering the source program 
so that the error does not occur. It 
must be emphasized that the cause of 
entry into the PL/I error handler was 
not the cause of the system dump. 

9. If the interrupt is not in the error 
handler, or one of the routines it 
calls, the highest probability is 
still that the program check exit was 
altered in the error handler and that 
an invalid branch has been made from 
one of the addresses in the TCA 
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because of overwriting. A careful 
check should therefore be made in the 
TCA. (See appendix A for map of TCA.) 
If this fails to produce results, 
return to stage 2 of the above 
procedure. 



Stand-alone Dumps 



Si Finding key areas in stand-alone 
dumps 



Section 3: Locating Specific Information 



This section tells the reader how to 
discover information from the dump. The 
section has been produced in a modular form 
for easy reference. The reader should look 
through the contents list below to discover 
the items in which he is interested, 
suggested methods of debugging a PL/I 
program from a dump are given in section 2 
of this chapter. Unless the programmer is 
experienced in using dumps,, or is looking 
for some particular item, the procedures in 
section 2 should be followed, rather than 
attempting to find various items through 
the information in this section. 



CONTENTS 



Key Areas of „a_PL/I,„Dump 
PI 



Statement number and address where 
error occurred (dump called from 
on- unit only) 



P2 Type of error (dump called from 
on- unit only) 

P3 Register contents at time of error or 
dump invocation 

P4 The DSA chain 

P5 The TCA 



Key_Areas of an ABEND Dump 



Housekeeping... Information in all Dumgs 

HI Following the DSA backchain 

H2 Associating instruction with correct 
module 

H3 Following calling trace 

Bf* Associating DSA with block 

H5 Finding relevant ONCA 

H6 Following the chain of ONCAs 

H7 Finding information from IBMBERR's 
DSA 

H8 Finding and interpreting register 
save areas 

H9 Register usage 

HIO Following free- area chain 

Hll Finding the task variable 

Hi 2 Block structure of program 
(static- backchain) 

H13 Forward' chain in DSA^s 

H14 -Action if error is in a library 
module 

HI 5 Discovering contents of parameter 
lists 

H16 Finding main procedure DSA 

H17 Finding the relationships between 
tasks 

H18 Finding the tasking appendage 

H19 Finding the TCA from the tasking 
appendage 



01 Finding address of interrupt 

02 Type of interrupt 

03 Register contents at point of 

interrupt VI 

04 The DSA chain 

05 The TCA V2 

06 Finding the program interrupt element 
(PIE) V3 



Automatic variables 
Static variables 
controlled variables 
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VU Based variables 

V5 Area variables 

V6 Variables in areas 



described in H5. 



P3£ gggister_Contents_at_Tiiiie gf__Error 

or Dump Invocation 



Control Blocks and Fields 



cl Quick guide to identifying control 
fields 



KEY AREAS OF A PL/ 1 DU^3P 



Pi; Stateirient Number and Address_where 
Error Occurred (DumE Called , from On-Unit 
onlYl 



Information required is the point at which 
the condition that caused entry to the on- 
unit occurred. This is identified in the 
trace information. If no trace information 
is generated, the method suggested for 
ABEND dumps can be employed. If the 
condition occurred in compiled code, the 
machine instruction being executed can be 
identified on the object program listing. 
This is done by subtracting the address of 
the program control section from the 
address of the interrupt and looking at 
this offset in the object program listing. 
The instruction thus found will be the one 
after the instruction that was last 
executed. 

Note: If PLIDUMP is called a number of 
times in a program a different user 
identifier should be used with each CALL 
statement so that the point at which the 
dump was taken is obvious. 



P2i Type of .Error_.( Applies .to_ Dump 

Callgd_from_,On-Unit only) 



The type of error is identified in the 
trace information, in terms of the type of 
on-unit entered and the reason for entry. 
The ONCODE is also given,, thus providing 
further indication of the cause of the 
condition. If the dump was called from an 
ERROR on-unit, an error message should have 
been generated before the dump. This again 
will give the cause of the error. 

If no trace information has been 
generated, the type of error can be 
discovered from the error code appearing in 
the ONCA associated with the interrupt. 
The method for finding the ONCA is 



If trace information has not been 
generated, the contents of the registers 
can be found from the save area in the DSA. 
The addresses of all DSAs appear in the 
trace information. The register contents 
required will depend on the situation. If 
PLIDUMP was called from an on-unit, the 
register contents at the time the condition 
was raised will be most useful, unless the 
condition was raised in a library module. 
If the condition was raised in a library 
module, the contents of the registers at 
the point where the library call was made 
will probably prove more useful. 

For a dump called from an on-unit the 
method of finding the register contents is 
as follows: 

1. Find the DSA of IBMBERR. The value of 
register 13 will be found in the 
chainback field at offset 4 of this 
DSA. The first byte will contain the 
segment no. (probably 'FF') and can be 
ignored for addressing purposes. 

2. If the interrupt was a program check 
interrupt (see figure 12.7), the 
contents of registers 14 and 15 will 
also be stored in the DSA, register 14 
at offset •5C'(92) and register 15 at 
offset '60' (96) from the head of the 
DSA. 

3 . Registers through 11 will be stored 
in the save area of the previous DSA, 
starting at offset '14' (20). 

4. If the interrupt was a software 
interrupt, the registers will be 
stored at offset •C"(12) of the DSA 
before IBMBERR 's DSA in the order 14 
through 11. See figure 12.7. 

Discovering_J.f_interrupt_j^s_prggram_check 
interrupt : If trace information is 
available, a check can be made on whether 
IBMBERRA or IBMBERRB was called. IBMBERRA 
is entered after program check interupts, 
IBMBERRB after software interrupts. If no 
trace information is available, the 
simplest method of discovering if the 
interrupt was a program check interrupt is 
to inspect bit 7 in byte X'56* (86) in 
IBMBERR 's DSA. This is set to zero for 
program check interrupts,, and to 1 for 
other interrupts. 

Finding register values if interrupt 
occurred in library routine: If on-unit 
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was entered from a library module, a search 
back through the DSA chain to the first 
compiled code DSA should be made. This can 
be discovered from the trace information or 
by following the backchain from IBMBERR's 
DSA (offset 4 in each DSA) until a 
procedure block, begin block, or on-unit 
DSA is found. This may be determined from 
flag bits 4 and 5 of a DSA, as follows: 



Bit a Bit 5 



DSA 

Procedure block 
Begin block 
On-unit 



P5: The TCA 



The address of the TCA is given in a PL/I 
dump. If 'B' (block option) is specified 
in the dump-options character string, the 
complete TCA (including the appendage) is 
printed separately from the body of the 
dump. 

The TCA is addressed by register 12. 
The format of the TCA is given in appendix 
A. The use of the various fields is 
explained in chapter 4. 



The value of register 12 can only be 
discovered in a DSA prior to a compiled 
code DSA, as it is not stored by library 
routines when they are entered. This means 
that the dummy DSA always contains the 
value of register 12. Register 12 should 
point to the TCA, whose address is also 
given at the head of trace information. 

No trace information generated; If no 
trace information has been generated, the 
register values on taking the dump will be 
printed at its head. The address of the 
DSA for PLIDUMP will be in register 13. 
The chainback can then be followed to find 
the DSA for IBMBERR. The DSA for IBMBERR 
can be recognized if an on-unit is 
involved, because it will be the DSA before 
the on-unit DSA. IBMBERR 's DSA will always 
be headed by a flag byte of hexadecimal 
'88* meaning that it is a library DSA in 
LIFO storage. To identify IBMBERR 's DSA 
for certain, register 15 of the previous 
block's DSA must be inspected to see if it 
points to the module IBMBERR. 



KEY AREAS OF AN ABEND DUMP 



Qll__Address_gf_Interru2t 



If the ABEND code is 4000 the address of 
the interrupt can be found from the second 
word of the PSW, which gives the address of 
the instruction following the point of 
interrupt. The PSW is held in subpool 5. 
A description of how to find the PSW is 

given in the publication OS^. Programmer's 

Guide_to_Debu2gin3. The associated 
statement number in the source program can 
normally be found by finding the last 
compiled code DSA, and finding the point at 
which the exit was made (register 14 in the 
save area) . The address of the program 
control section can then be subtracted from 
this address, and the offset compared to 
the listing will give the appropriate 
statement number. 

Finding the statement number is not 
likely to prove useful because of the 
circumstances in which an OS system dump is 
generated. The address found will usually 
be the address at which the error handler 
was entered before the program check exit 
was altered. The reason for entry into the 
error handler is not the cause of the dump. 
If the ABEND code is not 16000 see 06. 



P4: The DSA Chain 



The addresses of the DSAs are given in a 
PL/I dump if trace information and a 
hexadecimal dump are requested. If trace 
information is not requested, the address 
of the DSA for the dump routine can be 
obtained from register 13 at the head of 
the dump. The chainback field is held in 
the second word of the DSA. When the dummy 
DSA is reached, this chainback field will 
be set to zero. The DSA chain passes 
through DSAs in LIFO storage and DSAs in 
LWS (library workspace). 

See HI and figure 12.9 for details of 
how to follow the DSA chain. 



Q2i__TYEe__of_InterruEt 



The type of interrupt can be found from the 
first word of the PSW (see Principles of 
Operation for details). 



03 £ RggJi;§ter_Contents .at__the_Point_,of 

Interrupt 



Registers 14 through 2 appear in the PIE 
(program interrupt element) . Registers 3 
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10 



14 



18 



1C 



20 



24 



28 



2C 



30 



34 



38 



3C 



40 



44 



DSA 



Flags 



Backchain 



Not used 



R14C) 



R15(*) i.J 



RO 



R1 



R2 



R3 



R4 



R5 



R6 



R7 



R8 



R9 



RIO 



ffr 



Always stored by 
library 



Stored by library 
if required 



Rll J^ 



R 1 2 Stored by compiled code only 



(*) Not stored if hardware interrupt occurs 
Figure 12.9. The register save area in the DSA 
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through 13 are those printed in the save 
area trace. See 06 for finding the PIE. 



04: The DSA Chain 



Register 13 should point at the most recent 
DSA. The back chain can be followed from 
offset '4' of each DSA. see figure 12.9. 



05; The TCA 



Register 12 should point at the TCA. 



Element (PIE) 



The program interrupt element (PIE) will be 
found at the head of subpool 5. The PIE 
will be followed by registers 3 through 13 
and then the STAE work area. The STAE work 
area holds the last problem program PSW. 
This is the value required for finding the 
original cause of the ABEND if the ABEND 
code is other than 4000. 



STAND-ALONE DUMPS 



Sli Finding Key Areas in Stand-alone 

Dumps 



The- programmer should attempt to find the 
various PL/I key areas (TCA, DSA chain, 
etc.) discussed above. 

Further information on reading stand 
alone dumps is given in the publication OSj 
programmers Guide to_Debugging . 



For programs using multitasking the DSA 
backchain leads to the dummy DSA of the 
major task. The DSA of the block in which 
the task was attached is not included in 
the chain. To find this DSA the 'static' 
backchain held at offset X'58' (88) can be 
used provided the procedure attached as a 
task is internal to the attaching block. 
If the procedure is not internal the NAB 
value X'UC* (76) in the DSA before it will 
I12£2!^1y point to the required DSA. 

(The method of chaining during a 
multitasking program is explained in 
chapter 14. For relationship of NAB and DSA 
chaining see H13.) 



H2}_ Associating Ins tr uction with 

Correct. Statement and Program Block 



Statement Number and Program Block : The 
statement number and entry point associated 
with the interrupt will normally be given 
in a PLIDUMP. However, if they have to be 
found by the programmer, he should follow 
the method used by the error message 
modules. 

§^§fegB)g.Qlr- ?^^1^Q^ • ^t must first be 
established whether the GOSTMT option is in 
effect. This will, be indicated in the 
listing for the compilation. If the 
listing is not available it will be flagged 
in the compiled code DSA. (Flag bit 13 of 
the DSA flags is set to 'I'B.) If this bit 
is not set the table of offsets and 
statement numbers may be available, if this 
is not available statement numbers and 
offsets must be deduced from the object 
program listing. The method of using the 
table of offsets is described below under 
the heading "Using the Table of Offsets". 
If both statement numbers and the table of 
offsets are available it will probably be 
faster to use the table of offsets rather 
than the statement number table. 

The statement number is found by use of 
the DSA chain as described below: 



HOUSEKEEPING INFORMATION IN ALL DUMPS 



HI:, Following_the_DSA_Backchain 



Each DSA holds a backchain address in the 
second word. This word holds the address 
of the previous DSA. The end of the chain 
is marked by the dummy DSA whose first word 
contains the flag hexadecimal '82'. The 
backchain in the dummy DSA points to the 
external save area or is zero if the 
program was called from the system. (See 
P4 or D4 for finding the DSA chain) . 



1. Find the chain of DSAs. The most 
recent DSA should be addressed by 
register 13. 

2. If the DSA found is not a compiled 
code DSA, (in a compiled code DSA flag 
bits 4 and 5 are set to 'OO'E, 'Ol'B 
or *11'B) the interrupt was not in 
compiled code. If the interrupt was 
in compiled code, the interrupt 
address can be directly associated 
with a statement number. 

If the interrupt was not in compiled 
code, the address at which compiled 
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code was left must be discovered and 
this address associated with a 
statement number. To find the address 
at which compiled code was left: 

a. Chain back along the DSA chain 
until a compiled code DSA is 
reached (flag bits 4 and 5 set to 
•00', 'Ol', or 'll'B). 

b. The register 14 address saved in 
the DSA (offset 12X'C') will be 
the point to which the library 
module or other module would have 
returned if the call had been 
successfully completed. 

The address thus found is the address to 
be associated with a statement number. 

3. Chain back one DSA to the DSA before 
the compiled code DSA that has been 
discovered in 1 or 2 above. The 
register 15 value in this DSA (offset 
16 X'lO') is the entry point of the 
block. If this appears to give an 
invalid result, check to see whether 
the DSA is one of those used in 
interlanguage communication ( flag bit 
7 set to 'I'B and bit of flags 2 
(offset X'76') set to 'I'B). If this 
is the case chain back one more DSA 
and try again. 

4. At offset 8 from the entry point of 
the block, the address of the 
statement number table will be held. 

5. Calculate the offset between the value 
in the first word of the statement 
number table and the address for which 
a statement number is required. If 
the address for which a statement 
number is required is less than the 
address in the first word of the 
statement number table, then either an 
invalid branch has been made, or a 
compiler generated subroutine is being 
executed. If it is possible that a 
compiler generated subroutine is being 
executed return to the compiled code 
DSA and attempt to find a statement 
number associated with the values held 
first in register 6, and, if this 
gives an invalid or improbable result, 
then in register 14. if the second 
word in the statement number table is 
less than the offset between the 
address for which a statement number 
is required and the first word of the 
statement number table, it is not 
within the program control section and 
an erroneous branch has been made out 
of the program. 

6. If the offset is more than X'7FFF' the 
statement number will be held in the 
second or subsequent sections of the 



table. Obtain the number given by 
translating the offset into binary and 
ignoring the last 15 bits and step 
down this number of sections of the 
table. (For example, if the offset 
was X'8FFF', translate to binary = 
'1000 1111 1111 1111 'B, ignore last 15 
binary digits =1, therefore step down 
one section of the table. If the 
offset was X'lBFFF' the binary would 
be '0001 1000 1111 1111 1111 'B. 
Ignoring the 15 right hand bits leaves 
•ll'B therefore step down three 
sections of the table.) 

The address of the second section of 
the table is held at offset X'8' in 
the table, the address of the third 
section is held at the head of the 
second section, the address of the 
fourth section at the head of the 
second section and so forth. 

7. When the correct section of the table 
has been identified, search for the 
first offset in the table that is 
greater than or equal to the offset 
that is being searched for. Following 
this offset the statement number is 
given in two- byte hexadecimal format. 

Pfo^edur e_name : To find the entry point 
name, a chainback is made beyond the first 
procedure DSA found on the chain. Register 
15 in the save area before this procedure 
DSA will point to the entry point of the 
procedure. (Procedure DSA have flag bits 4 
and 5 set to 'OO'B. The register 15 value 
is held at offset 16 X'lO'.) 

The entry is preceded by a one byte 
field that holds the number of characters 
in the name. This one byte field is in 
turn preceded by the entry point name. 

Using the t able _of offsets : St at eroen t 

numbers can also be found by comparing them 
with the offsets in the offset and 
statement number table generated by the 
compiler when the OFFSET option is 
specified. 

Offsets are held from each primary entry 
point or a procedure or on-unit. To use the 
table of offsets find the entry point used 
by the program in the manner described 
above. Find the primary entry point for 
the procedure. (If the primary entry point 
was not used look at the object program 
listing to see the relationship between the 
entry point used and the primary entry 
point.) Note, the offsets given are froir 
the point marked *REAL ENTRY in the object 
program listing. This point is one byte 
after the end of the primary entry point 
name. 

If the interrupt occurred in an on-unit 
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it may be necessary to discover the type of 
on-unit entered before it can be 
identified. This is done by inspecting the 
DSA before the DSA of the on-unit. This 
DSA will be for IBMBERR. At offset 8U 
(X'S***) in this DSA the first byte of the 
error code will be held. Compare this with 
the values in figure 12.8. This will given 
an associated PL/I condition. It will be 
the on-unit for this condition that has 
been entered. If there is more than one 
on-unit for the condition, the on-unit 
entered must be deduced by studying the 
dump, and source and object listings. If 
the register 15 value appears to be invalid 
this may be caused by rechaining in 
interlanguage processing (see chapter 13). 
If this is possible, chain back one more 
DSA and try again. (To check if this has 
occurred see 3, above under "statement 
Numbers") . 



following iranner. 

1. Find the DSA before that of IBMBERR 
(follow back the DSA chain until 
register 15 in the save area points to 
IBMBERR). See Hi, H3, H7. If this is 
a library DSA (flag bits U S 5 set to 
•10') go to 3, below. 

2. Find the LWS addressed from this DSA. 
The address is held at offset X'48' 
(72). 

3. Find the offset from the LWS to the 
ONCA. This is held at offset 2 in the 

LWS. 

4. Add the offset to the address of the 
library DSA in LWS. 



H3j_ Following_Calling_rrace 



The calling trace can be followed because 
branches within the program are always made 
on registers 14 and 15. Hence register 15 
in each DSA points to the address that was 
branched to from that block. Register 14. 
points to the address to which control 
passed when the block was completed. By 
finding the entry point name (see H2 above) 
it is possible to follow the calling trace. 



H6i Following the Chain of ONCAs 



ONCAs are used to hold condition built-in 
function values. They are chained 
together, one being provided for every 
level of interrupt. The chainback field is 
in the first word of the ONCA. The duiriry 
ONCA is marked by a chainback field of 
zero. 



H7; Finding Information from IBMBERR *s 

DSA 



H4j_ Associating[_DSA_with__Block 



DSAs are associated with code by finding 
the register values in the preceding DSA 
register save area (H8) and using the fact 
that all branches are made via registers 14 
and 15. Register 14 in any DSA points to 
the instruction after the point at which 
control left that block. Register 15 
points to the address at which the next 
block was entered. The block in the source 
program can be identified by statement 
numbers or entry point, found as described 
in H2, above. 



H5i Finding Relevant ONCA 



The information held in IBMBERR 's DSA is 
used by the error message modules for 
information about the error. If the 
messages have not been generated the 
information can be deduced from the DSA. 
The contents of IBMBERR 's DSA are shown in 
figures 12.7. See H4 for associating DSAs 
with correct code. 



H8i Finding_and, Interpreting Register 

Save Areas 



Register save areas are held at offset 
X'C'(12) in all DSAs, including DSAs in 
LWS. Offsets and registers are shown in 
figure 12.10. Each DSA holds the register 
values as they were on exit from its block. 



When an interrupt has occurred in the error 
handler and a system dump has been 
produced, it is possible to discover the 
information that the error handler would 
have used to generate appropriate error 
messages. The ONCA holds values for the 
condition built-in functions. The 
appropriate ONCA can be found in the 



Note: Library routines store at least 
registers 14 through 4, and up to registers 
14 through 11; compiled code routines store 
registers 14 through 12. Thus the address 
of register 12 can always be found in the 
dummy DSA although it may not be in other 
DSAs. The contents of the register save 
area in the DSA of the block that called 
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HlOi go.l3:Oyi.n.g_gree~Area_Chain 



Register 


Compiled code 
usage 


Library usage 


RO 


work 


register 


Work register 


Rl 


work 


register 


Work register 


R2 


Prograiti base 
(♦,*♦) 


Work register 


R3 


Static base 


Program base 




(♦♦) 


(♦♦) 


R4 


Work 


register , 


Work register 


R5 


Work 


register 


Work register 
(if used) 


R6 


Work 


register 


Work register 
(if used) 


R7 


Work 


register 


Work register 
(if used) 


R8 
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Work register 
(if used) 


R9 


Work 
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Work register 
(if used) 


RIO 
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work register 
(if used) 


Rll 


Work 
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(if used) 


R12 


TCA pointer 


TCA pointer 




(' 


"*) 


(*♦) 


R13 


Current DSA 


Current DSA 




pointer (**) 


pointer (*♦) 


R14 


Branch 


Branch 




register 


register 


R15 


Link 


register 


Link register 



(♦) The contents of the program base 
register are saved during in-line 
record I/O and TRT instructions 

(**) Dedicated register, i.e., the 
contents remain unchanged 
throughout the execution of the 
associated compiled code or library 
routine 



Figure 12.10. Register usage 



IBMBERR are slightly different from normal 
if the interrupt was a hardware interrupt. 
See figure 12.7. 



The free-area chain connects the areas of 
non-LIFO dynamic storage that have been 
used and freed, but have not been absorbed 
into the major free area. See chapter 6, 
"Storage Management." The chain starts at 
offset 8 in the implementation-defined 
appendage, which is addressed from offset 
X'28'(40) in the TCA. The end of the chain 
is marked with a zero entry. 



Hll£ Finding _the Task Variable 



The task variable is held in the TCA at 
offset X'24' (36). 



Hl2j^ Block„ Structure of Program 

(Static Backchain) 



The block structure of the program can be 
followed from the address held at offset 
X'58'(88) in each compiled code DSA. This 
address holds the address of the compiled 
code DSA of the statically encompassing 
block. The chain thus formed is known as 
the static backchain. 



H13: Forward Chain in DSAs 



The forward chain in DSAs is not supported 
by the compiler. However, a forward chain 
through the LIFO stack can normally be 
followed by use of the NAB pointer. The 
NAB pointer is held at offset X'4C'(76) 
from the head of each DSA. The last 
pointer in the chain points to the major 
free area. If the NAB pointer contains 
anything except 'FF' in its first byte, the 
chain cannot be followed,, because it is net 
contained in a single LIFO segment. The 
address required is held in the last three 
bytes of NAB; the first byte contains the 
segment number (see Cl) . The forward chain 
includes only those DSAs in the LIFO stack 
and does not include any DSAs in LWS. 



H9£ Register. Usage 



H,1;!:^l_^.^gtion_if _grror is in a Library 
Modul< 



Register usage is fully discussed in 
chapter 2, "compiler Output." A summary of 
register usage, showing which registers are 
always used for a particular purpose, is 
given in figure 12.10. 



The fact that the interrupt or the error 
was discovered during the execution of a 
library module suggests that a check must 
be made on the data that is being passed to 
the module. 



224 



To discover the contents of a parameter 
list see H15. 



HlS.^.^ Discoyerinc} contents of Parameter 

Lists 



Parameters are passed in a list of words 
pointed to by register 1, except during 
stream I/O. To find the position of a 
parameter passed to a program, find the 
value of register 1 in the save area of the 
DSA (see H4) of the calling block. 
Register 1 will then locate the parameter 
list. If the list is in static storage, 
this can be compared with the static 
storage listing. The name of the called 
routine can be discovered (H3). The 
correct parameters for PL/I library 
routines are given in the appropriate 
library PLM. 



HI62 gJQding^ Main Procedure DSA 



The main procedure DSA can be found by 
following the backchain of DSAs to the 
dummy DSA. The address of the main 
procedure DSA will be given by the last 3 
bytes of NAB in the dummy DSA. NAB is held 
at offset X*UC'(76) in the dummy DSA. The 
address of the dummy DSA is held at offset 
X*24*(36) in the TCA appendage, which is 
addressed from offset X*28*(40) in the TCA. 
The dummy DSA can be recognized by the 
presence of X*82* in the flag byte. 



Hl7i ginding_the_RelationshiE .between 

Tasks " 



The relationship between tasks can be 
discovered from the chains in the tasking 
appendage. The chain held at offset X'28* 
(40) points to the tasking appendage of the 
most recently attached subtask. 

The chain at offset X'2U» (36) points to 
the task with the same attaching task that 
was attached befQre the task being 
inspected (elder sister). If there is no 
such task the field is set to zero. 

The chain at offset X'20* (32) points to 
the subsequently attached task with the 
same attaching task (younger sister). If 
there is no younger sister this chain 
points to an offset within the tasking 
appendage of the parent task. An attempt 
to continue along the chain results in a 
zero field being met. (See figure 14.7.) 



To Find the Parent Task 



Search along the chain held at offset X'20' 
(32) in each tasking appendage. When this 
field is zero the tasking appendage of the 
parent task has been reached. The start of 
this tasking appendage is at an offset of 
X'-8'(-8) from the address held in the 
pointer of the previous tasking appendage. 
(See figure 14.7.) 



To Find all Subtasks of a Task 



The address of the most recently attached 
subtask is held at offset X'28» (40) in the 
tasking appendage. Other subtasks can be 
found by following the chain held at offset 
X'24* (36) in the tasking appendage until a 
zero field is reached. This will be the end 
of the chain and is the first of the active 
subtasks to be attached by the task. (See 
figure 14.7.) 



To Find Sister Tasks 



Previously attached sister tasks (elder 
sisters) can be found by following the 
chain held at offset X'24' (36) in the 
tasking appendage. 

Subsequently attached sister tasks 
(younger sisters) can be found by following 
the chain held at offset X'20* (32) in the 
tasking appendage. When a zero field in 
this chain is reached, the parent task has 
been found. The most recently attached 
sister task is the last one whose chain 
field does not hold a zero value. The word 
after the zero value will point to the 
tasking appendage of this task. 

The method used for chaining tasks is 
explained in chapter 14, and shown in 
figure 14.7. 



H18; Finding thg_Tasking Appendac 



The address of the tasking appendage is 
held at offset X'2C' (44) in the TCA and at 
offset X'50' (80) in the dummy DSA of the 
attaching task. 
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HI 9; Finding __the^TCA_froin_the, Tasking 

Appendage " " 



PRV. If there is no previous allocation, 
the address is set to zero. 



The TCA is addressed from X'2C* 
TCA tasking appendage. 



(44) in the 



V4: Based Variables 



FINDING VARIABLES 



The value of the variables in the program 
at the point of interrupt can be discovered 
by using the compiled code listing as a 
guide to their addresses, and then finding 
these addresses in the dump. The method 
used depends on the type of variable. 



VI: Automatic Variables 



Automatic variables can be found by using 
an offset from the DSA of the block in 
which they were declared. This information 
appears in the variables offset map 
generated when the compiler MAP option is 
used. If the compiler MAP option has not 
been used the information can be deduced 
from compiled code. (For finding DSA 
associated with block see H4) . 



V2: Static Variables 



Static variables are normally addressed by 
an offset from register 3. This offset is 
given in the variables offset map generated 
when the compiler MAP option is used. If 
the compiler MAP option has not been used 
the offset can be deduced by studying the 
listing of compiled code. The value of 
register 3 can be found in the save area of 
the DSA. (For finding DSA associated with 
block see H4) . 



Based variables are located by finding the 
value of the defining pointer. This value 
is found by using one of the methods 
described above to find static, automatic, 
or controlled variables. If the pointer is 
itself based,, its defining pointer must be 
found and the chain followed until the 
correct value is found. 

Typical code would be the following: 

For X BASED (P) , with P AUTOMATIC 

58 60 D 088 L 6,P 

58 EO 6 000 L 14, X 

P is held at offset X'88' from register 
13, and this address points at X. 

Care must be taken when examining a based 
variable to ensure that the pointers are 
still valid. 



V5j_ Area Variables 

Area variables are located in one of the 
ways described above, according to their 
storage class. 

Typical code would be: 

For area variable A declared AUTOMATIC 

41 60 D 088 LA 6, A 

The area would start at offset X'88" 
from register 13. 



V3: Controlled Variables 



V6: Variables in Areas 



As described in chapter 2, controlled 
variables are addressed by an anchor word 
that is held in the pseudo-register vector. 
This can be identified from compiled code. 

The address in the pseudo-register 
vector is the address of the data or, in 
certain circumstances (see appendix A), of 
a descriptor or a locator /descriptor. The 
data is preceded by a control block - the 
controlled variable control block. The 
address of the previous allocation is held 
at an offset of -8 from the address in the 



Variables in areas are found by locating 
the area and then using the offset to find 
the variable. 



CONTROL BLOCKS AND FIELDS 



For simplicity, the methods of finding 
various control blocks are placed in an 
alphabetic table. Details of the control 
blocks can be discovered from the relevant 
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chapters (see index) or from appendix A. 

As well as control blocks, various other 
items are included in the list. Where 
necessary, cross-reference is made to other 
sections in this chapter. 



Cli fijJiclS.. Guide, to Ident if Ying...Control 

Fields 



Filename 



Free-area chain 



Locator/descriptor 



addressed from 
offset X'lO' (16) in 
FCB 

offset X'8' in 
implementation- 
defined appendage, 
which is addressed 
from offset X'28' 
(40) in TCA 

deduced from object 
program listing 



Automatic variables 

Backchain 

DSA backchain 
ONCA backchain 

BOS 

Beginning of segment 



see "Variables" 



offset X'U' in DSA 
offset X'O* in ONCA 

offset X«8* from TCA 



Controlled variables see "Variables" 



DCLCB 

Declare control Block 

DCB 



Deduced from object 
program listing 

addressed from 
offset X'lH' (20) in 
FCB 



LWS 

Library workspace 



NAB 

Next available byte 

ONCA 
ON-communications area 



ONCB 

ON-control block 
start of dynamic 
ONCB chain 



addressed from 
offset X'48' (72) in 
every DSA 

offset X'UC (76) in 
DSA 

the offset of the 
associated ONCA is 
held in a halfword 
at offset X"2' in 
each section of LWS 



offset X'60' (96) in 
DSA 



ENVB 

Environment Block 



offset X'c* (12) in 
DCLCB 



- first static 
ONCB 



offset X'SC (92) in 
DSA 



DED 

Data element 

descriptor 

Diagnostic statement 
table 



DFB 

Diagnostic file block 



deduced from object 
program listing 



addressed from 
offset X*8' from 
entry point of main 
procedure 

addressed from 
offset X*40' (64) in 
TCA 



On-cells 



OCB 

Open control block 



Parameter lists 



addressed from 
offset X'70' (112) 
in DSA 

deduced from object 
program listing and 
parameter list of 
open module, IBMBOCL 

object program 
listing and static 
storage map 



DSA 

Dynamic storage area 



EOS 

End of segment 

Event variable 



FCB 

File control block 



addressed by 
register 13 (see P3 
and D3) 

offset X'C* (12) in 
TCA 

deduced from object 
program listing and 
knowledge of 
parameter lists of 
I/O and wait modules 

identified in PL/I 
dumps. Addressed 
via PRV and DCLCB 



Register values 

RCB 

Request control block 



SIOCB 

Stream I/O control 

block 

Symbol table 

Symbol table vector 

Statement number 
table 



See P3 and 03 

object program 
listing and static 
storage map 

object program 
listing 



Static listing 

Static listing 

See Diagnostic 
statement table 



Flow statement table 



addressed from 
offset X'UC* (76) in 
TCA 



Static storage 



addressed by 
register 3 in 
compiled code. See 
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segment number 



Tasking Appendage 



Task variable 



P3 and 03 

first two bytes of 
BOS, EOS, or NAB. 
•FF«=1,'FE*=2 etc.* 

addressed from X'2C* 
(*»a) in the TCA. 

addressed from X'24' 
(36) in the TCA. 



from offset within 
areas shown in 
compiled code. See 
V6 

*When the first two bytes of EOS and BOS 
are greater than two bytes of NAB, it means 
that an extra segment of storage has been 
used, but not yet freed. See chapter 6, 
"Storage Management." 



TCA 

Task communications 

area 

Variables 

automatic 



based 



controlled 



static 



area 



Variables in areas 



addressed by 
register 12. See P3 
and D3 



offset from 
DSA of block in 
which they are 
declared. As shown 
in variables offset 
map. see VI. 

address of the 
pointer must be 
deduced from the 
object program 
listing. This gives 
the address of the 
variable, see V2 

PRV offset 
referenced in 
compiled code holds 
latest allocation of 
the variable. A 
chain-back through 
the previous 
allocation can be 
made using the 
header chain. See 
V3 

offset from register 
3 is shown in 
variables offset 
map. see VU. 

as for other 
variables depending 
on storage class, 
see V5 

find address of 
area. Find variable 



Special Considerations for Multitasking 



The major difference between a dump of a 
multitasking program and the dump of any 
other PL/I program is that certain relevant 
items are held within the control task. 
For this reason, the control task is always 
dumped as well as the current task. 

The contents of the dump of a tasking 
program depend on the dump options 
specified. If A (all) is used all the 
tasks will be dumped. If O (only current 
task) is specified the control task and the 
current task will be dumped. 

The dump is carried out within the 
control task and this prevents access to 
the tasking housekeeping during the 
execution of the dump. However, this does 
not prevent access by other tasks to PL/I 
variables which may be dumped. Subtasks of 
the current task can access and alter 
values within the ISA of the current task. 
Consequently the values of the variables 
printed cannot be guaranteed to be those 
that were current at the invocation of the 
dump. 

As explained in chapter 14, the DSA 
chaining differs slightly when a program is 
multitasking. The backchain passes through 
the dummy DSA of the task and ends at the 
dummy DSA of the major task. The DSA of 
the block in which the task was attached is 
no t included in the backchain. 

Compiled code and the static control 
sections generated by the compiler are 
always held in storage associated with the 
control task. 
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Calling routine 



Call to routine in 
other language 



real 
path 



I 
1 

apparent path 

I 

I 

I 

I 




Save old environment, 
set up new environment. 
If necessary, provide dummy 
data aggregate arguments 



Called routine 



Routine of other language 
carries out required 
task and returns 



real 
path 



▼ 
I 
I 
I 
I 
I 

apparent path 
I 
I 



real 
path 




Restore former environment. 
Where necessary, assign 
values in dummy data 
aggregate arguments to 
real arguments 



Calling routine 



Continuation of procedure in 
original language 



real 
path 



Figure 13.1. The principles of interlanguage communication 
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Chapter 13: Interlanguage Communication 



The OS PL/I Optiirizing Compiler allows 
subroutines compiled on IBM OS COBOL or 
FORTRAN compilers to be used in PL/I 
programs compiled on the optimizing 
compiler. similarly, it compiles PL/I 
programs that can be run as subroutines of 
either COBOL or FORTRAN programs. 

I Facilities are also provided to overcome 

I the addressing problems when passing 

I arguments to assembler language routines. 

I These are described under the heading 

I "ASSEMBLER Option" later in this chapter. 

A full description of how to use the 
interlanguage communication facilities is 
given in the language reference manual for 
this compiler. A detailed description of 
the PL/I library routines involved is given 
in the resident library PLM. This chapter 
explains the basic design principles used 
and will assist in understanding the 
situation in main storage during the 
execution of a program involving 
interlanguage calls. 

The interlanguage facilities are 
summarized below for background 
information. 



or FORTRAN in the OPTIONS attribute. If 
the programmer wishes to take advantage of 
the PL/I error-handling or interrupt- 
handling facilities in a COBOL or FORTRAN 
routine, the INTER option must be included 
in the declaration. When a PL/I procedure 
is to be called by COBOL or FORTRAN, the 
keyword COBOL or FORTRAN should be included 
in the OPTIONS option of the PROCEDURE or 
ENTRY statement. To override the creation 
or remapping of dummy arguments for 
aggregates the options NOMAP, NOMAPIN, and 
NOMAPOUT can be used. 

The compiler also allows the 
specification of the COBOL option in the 
ENVIRONMENT attribute of a PL/I file. This 
is separate from the interlanguage 
facilities described above, and is a method 
of allowing data sets produced by programs 
of one language to be used by programs of 
the other language. The use of the COBOL 
option in the ENVIRONMENT attribute is 
described in the last section of this 
chapter. 



Background to Interlanguage 
Communication 



summary o f Interlanguage Facili tie 



The interlanguage facilities allow any 
number of calls to be made, and calls to 
both COBOL and FORTRAN routines can be made 
in the same program. PL/ I can call COBOL 
that calls PL/I that calls FORTRAN; FORTRAN 
can call PL/I that calls COBOL, and so on. 
All calls must, however, be made either to 
PL/I or from PL/ I. Calls cannot be made 
directly between COBOL and FORTRAN. 
Options allow the programmer to specify 
that PL/I interrupt-handling facilities 
will be available through the COBOL or 
FORTRAN routines for those program checks 
that are not handled by COBOL or FORTRAN, 
options also allow the programmer to 
specify whether he wishes data aggregates 
to be automatically re-formatted when 
passed as arguments. (The programmer may 
wish to carry out the re- formatting 
himself.) 

The language involved is fully described 
in the language reference manual. Briefly, 
it is as follows. For a PL/I procedure to 
call a COBOL or FORTRAN routine, the name 
of the routine must be declared as an 
external entry point with the option COBOL 



The major problems involved in allowing 
procedures written in PL/I to be used with 
programs written in COBOL or FORTRAN are: 

1. The existence of different data types 
in the different languages. 

2. The different methods of holding data 
aggregates in the different languages. 

j 3. PL/I's use of locators when passing 
I areas, arrays, strings, and structures 
j as arguments. 

U. The different environment required for 
each language. This consists of : 

a. Different methods of handling 
program checks and consequently a 
requirement for the issuing of new 
SPIE macro instructions when a new 
language is entered. 

b. The dependence of PL/I and FORTRAN 
on initialization and termination 
routines to set up and discard 
their environments. 

The first of these problems must be solved 
by the programmer himself, by ensuring that 
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PL/I COMPILED CODE 




PL/I LIBRARY ROUTINE 



Call inter-language 
housekeeping routine 



Set up required 
environment 



COBOL or FORTRAN 
COMPILED CODE 



Remap data aggregates 
as dummy arguments 



Call COBOL or FORTRAN routine 



Call inter-language 
housekeeping routine ^ 



Restore PL/ 1 
environment 



Place dummy argument 
values in data aggregates 
if necessary 



Continue 



Execute 
required 
program 




Figure 13.2. Calling sequence when PL/I calls COBOL or FORTRAN 
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arguments passed between the routines are 
of suitable data types. (Information in 
the language reference manual for this 
compiler enables the programmer to do 
this, ) 

The other problems mentioned above are 
handled automatically by the interlanguage 
communication facilities of the compiler. 
They are summarized below. 



DIFFERENCES IN DATA AGGREGATES 



Structures in PL/I and COBOL, and arrays in 
PL/I and FORTRAN, are held in different 
manners. 

COBOL structures are mapped as they are 
declared, with the structure starting on a 
doubleword boundary and each item 
separately aligned. PL/I structures are 
mapped in a manner that minimizes padding. 

In FORTRAN, multidimensional arrays are 
held in column-major order. In PL/I, they 
are held in row-major order. Thus the 
second element in a FORTRAN two-dimensional 
array has the subscript (2,1), whereas the 
second element in a PL/I two-dimensional 
array has the subscript (1,2), 

Structures are not available in FORTRAN. 
COBOL data with the OCCURS option, which 
can be equivalent to PL/I arrays, is held 
in row major order, as are PL/I arrays. 



I USE OF LOCATORS 



When passing arguments, PL/I passes the 
address of locators for areas, arrays, 
strings, and structures rather than the 
address of the items themselves. This is 
because the routine that receives the 
arguments may require information about 
bounds or sizes of the data passed, and 
this is accessible through the locator. 
Other languages,, however, expect the 
address of the data to be passed. The 
correct type of paramter list must 
therefore be set up when an interlanguage 
call is made. 



DIFFERENCES OF ENVIRONMENT 



PL/I, COBOL and FORTRAN all have different 
methods of handling program checks. PL/I 
allows the programmer to handle all program 
checks. FORTRAN allows the programmer to 



handle certain program checks. COBOL 
leaves program checks almost entirely in 
the hands of the system. Because of the 
different requirements, a new SPIE macro 
instruction must be issued whenever control 
passes between languages. The INTER option 
demands that program checks are analyzed 
when they occur and that they are passed to 
the appropriate language. If they are to 
be passed to PL/I, the PL/I environment 
must be restored. For these reasons the 
INTER option demands that further SPIE 
macro instructions be issued. 

IBM FORTRAN compilers and the PL/I 
optimizing compiler rely upon 
initialization routines to set up an 
environment in which the compiled code 
routines can operate. In FORTRAN, the main 
task of the initialization routine is to 
issue a SPIE macro instruction to initiate 
the FORTRAN error-handling scheme. In 
PL/I, the initialization routines prepare 
for the PL/I error-handling schemes and 
also prepare the way for dynamic storage 
allocation. During PL/I initialization 
routines, register 12 is pointed at the 
TCA, which is used for addressing a number 
of housekeeping fields and library 
routines. Register 13 is pointed at a DSA 
which contains a standard save area, a NAB 
pointer pointing to the next available byte 
of last-in, first-out dynamic storage, 
various other housekeeping fields, and 
storage for variables declared automatic. 
(See chapter 1 and chapter 5 for a 
discussion of the PL/I environment.) 

When PL/I is called from either COBOL or 
FORTRAN the PL/I environment must be set up 
before the program can be run. Similarly, 
when PL/I calls another language, the 
environment suitable for the program that 
has been called must be set up, and the 
PL/I environment saved so that it may be 
restored on return to PL/I. 



THE PRINCIPLES OF INTERLANGUAGE 
COMMUNICATION 



Figure 13.1 shows the method used to handle 
interlanguage communication problems. 
Interface code is inserted immediately 
before and immediately after the execution 
of a routine in a different language. This 
code saves the existing environment and 
sets up the required environment. Where 
necessary it creates dummy aggregate 
arguments of the correct format. The 
interface code is divided between compiled 
code and library routines. Compiled code 
handles data aggregate arguments and calls 
a library routine to handle the problems of 
environment. Three PL/I resident library 
routines are used; one for calls to each 
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language. These routines are known as the 
interlanguage housekeeping routines. 

The interface code is always placed in 
PL/I, because it is the PL/I compiler that 
manages the interlanguage facilities. 
However the position of the code depends on 
whether PL/I is the called or calling 
program . 



the required PL/I routine. Control returns 
to the original caller by way of the 
interface routine which again handles the 
interlanguage problems before returning. 

The sequence of events when PL/I is the 
called program is shown in figure 13.3 and 
is summarized below. 



1. 



A COBOL or FORTRAN routine calls the 
PL/I routine. 



PL/I Calls COBOL or FORTRAN 



When the calling program is PL/I the 
interface code is placed immediately before 
and immediately after the call to the COBOL 
or FORTRAN routine. The sequence, is shown 
in figu;re 13.2 and is summarized below. 

1. Compiled code remaps data aggregate 
arguments if necessary. 

2. compiled code calls the interlanguage 
housekeeping routine, which handles 
environment problems. 

3. compiled code calls the COBOL or 
FORTRAN routine. 

4. On return from the COBOL or FORTRAN 
routine, compiled code calls the 
interlanguage housekeeping routine to 
restore the PL/I environment. 

5. Compiled code re-maps dummy data 
aggregate arguments if any, and 
continues. 



2. 



3. 



H. 



5. 



6. 



Control passes to the interface 
routine which has been compiled with 
the BSD name of the PL/I routine or 
entry point. 

The interface routine calls the 
interlanguage housekeeping routine to 
handle environment problems. 

The interface routine handles data 
aggregate arguments as necessary. 

The interface routine calls the 
required routine. 



Control returns from the required 
routine to the interface routine, 
interface routine handles data 
aggregate arguments as necessary. 



The 



The interface routine calls the 
interlanguage housekeeping routine to 
handle environment problems. 

Control returns from the interface 
routine to the original caller. 



The code generated by the compiler is shown 
in figure 13.3. 



Retaining_the__Enyironment 



FORTRAN or COBOL Calls PL/I 



When the called program is PL/I, the 
necessary interface code is placed at the 
start and finish of the PL/ I program. The 
interface code is compiled as an 
encompassing routine to the required PL/I 
routine. 

The method used, is to compile the PL/I 
program in the normal way except that it is 
compiled as internal to an interface 
procedure that contains the interface code. 

This interface,, or encompassing 
procedure is given the external name of the 
PL/I procedure and is thus called by the 
other-language routine. The interface 
procedure, when it has called the 
interlanguage housekeeping routine and 
handled the data aggregate arguments, calls 



The overhead of setting up PL/I and FORTRAN 
environments every time a routine is called 
could become considerable if the routine 
were called a large number of times. To 
prevent this overhead,, the environment is 
retained until the routine that calls the 
other language routine is itself 
terminated. This is done by a rearrangement 
of the save area chaining, so that the PL/I 
and FORTRAN termination routines are not 
entered until the calling program is itself 
terminated. 

The arrangement introduces certain 
housekeeping problems which are resolved by 
inserting further save areas into the 
chain. These save areas have register lU 
values that result in control being passed 
to subroutines of the interlanguage 
housekeeping routines. These subroutines,, 
known as tail code, handle problems such as 
preserving values passed from the caller to 
the caller's caller. 
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SOURCE 


1 




P13P2 


rPROC; 


2 


1 




DCL FRED OPTIONS (COBOL), 
1 STRUCTURE, 

2 C CHAR (1), 

2 D FIXED BINARY (31,0); 


3 


1 




CALL FRED ( STRUCTURE) ; 


4 


1 




END; 



♦ STATEMENT NUMBER 3 






000066 


41 


00 





008 




LA 


00006A 


58 


10 


D 


04C 




L 


00006E 


IE 


01 








ALR 


000070 


55 


00 


C 


OOC 




CI 


000074 


47 


DO 


2 


018 




ENH 


000078 


58 


FO 


C 


048 




I 


.00007C 


05 


EF 








EAIR 


00007E 










CI. 4 


ECU 


00007E 


50 


00 


D 


04C 




ST 


000082 


41 


11 





000 




lA 


000086 


50 


10 


D 


0A8 




ST 


00008A 


E2 


03 


D 


088 D 


0B3 


N.VC 


000090 


58 


80 


C 


088 




I 


00009U 


D2 


03 


1 


000 D 


088 


NVC 


00009A 


58 


90 


C 


0E4 




I 


00009E 


50 


90 


1 


004 




ST 


0000A2 


58 


FO 


3 


OOC 




I 


0000A6 


18 


11 








LR 


0000A8 


05 


EF 








EAIR 


OOOOAA 


50 


70 


3 


030 




ST 


OOOOAE 


96 


80 


3 


030 




CI 


0000E2 


IB 


55 








SR 


0000B4 


41 


10 


3 


030 




lA 


0000E8 


58 


FO 


3 


034 




I 


OOOOBC 


18 


67 








IR 


OOOOBE 


05 


EF 








EAIR 


OOOOCO 


58 


FO 


3 


010 




I 


0000C4 


05 


EF 








EAIR 


0000C6 


C2 


03 


E 


088 7 


000 


WVC 


OOOOCC 


58 


FO 


D 


088 




I 


OOOODO 


E2 


03 


D 


0B3 C 


088 


KVC 


0000D6 


58 


60 


7 


004 




I 


OOOODA 


50 


60 


D 


0E4 




ST 



0,8(0,0) 

1,76(0,13) 

0,1 

0,12(0,12) 

CI. 4 

15,72(0,12) 

14,15 

* 

0,76(0,13) 

1,0(1,0) 

1,168(0, 13) 

KKSF. 1 + 16(4) ,S 

TURE.C 

8,WKSF. 1+16 

0(4, 1) ,WKSF.1+ 

9, STRUCTURE. D 

9,4(0, 1) 

15, A. .lEMBIECA 

7,1 

14,15 

7,48(0,3) 

48(3), X'80' 

5 5 

l!48(0,3) 

15,52(0,3) 

6,7 

14,15 

15, A. .lEKEIECC 

14,15 

KKSF. 1+16(4) ,0 

15,WKSF. 1+16 

STRUCTURE. C (4) 

P. 1 + 16 

6,4(0,7) 

6, STRUCTURE. D 



TRUC 



16 



(7)~| 
,WKS L 



Get VDA for dummy 
arguments 



Place new value in NAB 



Move structure into 
dummy 



Branch to interlanguage 
housekeeping routine 

Set up argument list 

Branch to COBOL routine 

Branch to interlanguage 
housekeeping routine 

Move values from dummy 
to real arguments 



Figure 13,3. code generated when PL/I calls a COBOL routine 
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COBOL or FORTRAN COMPILED CODE 



PL/I COMPILED CODE "ENCOMPASSING PROCEDURE" 



Call PL/I routine 



Call inter-language 
environment routine 



PL/I LIBRARY ROUTINE 



Set up PL/I 
environment 



Generate dummy data aggregate arguments 
if necessary 



PL/I COMPILED CODE REQUIRED 
PROCEDURE 



Call required PL/I 
procedure 



Execute 
required 
program 



Remap data aggregates if necessary 



PL/I LIBRARY ROUTINE 



Call inter-language 
environment routine 



Restore COBOL or 
FORTRAN environment 



Return to COBOL or FORTRAN 



Continue 
Figure 13. U. The sequence of events when FORTRAN or COBOL calls PL/I 
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SAVE AREA CHAINING 



Standard save area of outer 
procedure/calling routine (if any) 



© 





— ^ 


COBOL or FORTRAN calling routine save area 






^ 




Short save area 


^ 


^ 








^ 


Interlanguage routine save area 
(Save area 2 in ZCTL) 


^ 




w 


PL/I initialization routine save area 








^ 


PL/I encompassing procedure save area 


^ 














PL/I required procedure save area 









© 



© 



© 



© 



© 



Rearrangement of save area chaining takes place after the 
first call to PL/I, so that the PL/I environment is not discarded 
until the calling routine itself is finished. 

Save areas that return control to the PL/I initialization routine 
and interlanguage housekeeping routine are placed before the 
calling routine. (The numbers 1-7 in the diagram show the 
order of backchaining). 



Figure 13.5* 



Chaining of save areas when PL/l is called from a COBOL or FORTRAN 
principal procedure 
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Handling Changes of Environment 



Intjerlanguage. Housekeeping Routines _and 
their Control Blocks " 



Changes of environment are handled by three 
resident library interlanguage housekeeping 
rrodules, one for calls to each language. 
Common features are described below. A 
more detailed description follows for each 
routine. The routines are: 

IBMBIEF for calls to FORTRAN 
IBMBIEC for calls to COBOL 
IBMBIEP for calls to PL/I 

The job of these routines is the saving and 
restoring of environments. This involves 
issuing SPIE macro instructions suitable 
for the called routine and saving the PICA 
of the calling routine so that a suitable 
SPIE macro instruction can be issued before 
return. For PL/I it also involves storing 
information about dynamic storage 
allocation, and the TCA address. 

The information required when setting up 
and restoring environments is held in three 
chained control blocks: 

1" IBMBILCl This is a control section 
included in every interlanguage 
housekeeping routine. It contains 
flags to indicate whether the PL/I, 
FORTRAN or COBOL environments already 
exist and, if any do exist, contains a 
pointer to ZCTL. 

2* ZCTL This holds PICA addresses and the 
TCA address. It is chained to a series 
of interlanguage VDAs. It also holds 
flags indicating which languages are 
currently active, 

ZCTL is generated on the first of a 
series of interlanguage calls and is 
retained until that series of calls is 
completed. For calls to FORTRAN and 
PL/I it is retained until the routine 
that made the first interlanguage call 
is itself terminated. 

Also held in ZCTL are the additional 
save areas used when the chaining is 
altered. These are known as save area 
1, save area 2, and the ghost save 
area. The uses of these save areas 
are given in the individual module 
descriptions. 

3* Interlanguage VDAs These hold flags 

indicating"'which languages were active 
before the latest call was made, the 
address of the callers PICA, the 
address of the most recent PL/I DSA. 



An interlanguage VDA is acquired for 
every interlanguage call and discarded when 
the called routine is terminated. 
Interlanguage VDAs are held in the PL/I 
LIFO storage stack. 

The methods of chaining used for these 
control blocks when PL/I is the called and 
the calling language is shown in figures 
13.6 and 13.7. IBMBILCl contains a pointer 
to ZCTL and ZCTL contains a pointer to the 
most recent interlanguage VDA. 
Interlanguage VDAs hold pointers to 
previous interlanguage VDAs, if any. If 
there are none, the pointer field is set to 
zero. 

There is one interlanguage VDA for each 
interlanguage call. A VDA is set up when 
the call is made and discarded when the 
associated routine is terminated. The VDAs 
hold a record of the ZCTL flags that 
existed before they were called. These 
flags are placed in the VDA before the 
flags are altered and restored in ZCTL when 
the VDA is discarded. Thus ZCTL always 
contains a record of the active l an guages. 
This information is necessary when handling 
STOP statements. 

The flags in IBMBILCl contain a record 
of the environments that are active. These 
flags are used to test whether it is 
necessary to call the FORTRAN or PL/I 
initialization routines, or whether the 
environment can be restored from the 
information saved in ZCTL and the 
interlanguage VDAs. 



Handling FORTRAN and PL/I 
Initialization/Termination Routines 

FORTRAN and PL/I environments are set up by 
initialization routines and discarded by 
termination routines. To save the 
overheads of executing these routines on 
each call to the language the save area for 
the termination routine is placed above 
that of the calling program. On the first 
call the PICA address and, for PL/I only, 
the current DSA and TCA address are saved. 
For subsequent calls this information is 
restored by the interlanguage routines and 
no call made to the initialization routine. 
Figure 13.8 shows the principles involved. 

The rearrangement of the save area chain 
results in certain problems, for example 
returning parameters from the caller to the 
caller's caller. To overcome these 
problems additional save areas are inserted 
in the chain. These save areas result in 
control passing to subroutines in the 
interlanguage housekeeping routines known 
as tail code. Details are given in figures 
13.9 and 13.10 and in the individual module 
descriptions below. 
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1 


1 


Initial situation 

IBMBILC1 is set up as a control section by the PL/I interlanguage 
routines, its first word and flags are initially zero. 




IBMBILC1 








IBMBILC1 






ZCTL 










Zero 






y 


Address of ZCTL 




Zero 
I 


Zero 

1 






X 










I \ 
COBOL FORTRAN 
flag flag 


















2 


Call FORTRAN from PL/I (IBMBIEF) 

The compiler generates a call to the interlanguage communications 

routine. This routine: 

1. Sets up ZCTL after testing for zero pointer in IBMBILC1. 
Acquires an interlanguage VDA. 

2. Sets ZCTL pointer to interlanguage VDA, and IBMBILC1 
pointer to ZCTL. 

3. Sets FORTRAN flag in IBMBILC1. Saves R12 in ZCTL, 
R13 in interlanguage VDA. 

4. Calls FORTRAN library to initialize FORTRAN SPIE 

5. Resets program check exit as required. 

6. Returns to compiled code, which calls FORTRAN 
procedure. 




IBMBILC1 






ZCTL 






VDA (First) 










y 


^ 


— 


X 


> 








X 




FORTRAN 
interrupt handling 
information 




R13 


















R12 








3 


Call PL/I from FORTRAN (IBMBIEP) 
The PL/I program, because it is declared with the option 
FORTRAN, will have been compiled inside an encompassing 
procedure. The encompassing procedure is the one called by 
FORTRAN. The encompassing procedure calls the inter- 
language communications routine IBMBIEP, which: 

1. Checks IBMBILC1 to see if either FORTRAN or COBOL 
flag is set. As one flag is set, restores registers. 

2. Issues PL/I SPIE and STAE and stores interrupt handling 
information of calling program in interlanguage VDA. 

Control then returns to the encompassing program, which calls 
the required PL/I program. 




IBMBILC1 


ZCTL 






VDA (First) 






y 


^ 


^ 


/▼ 








X 




^^^^^^^^^^^^^^ 




FORTRAN 
interrupt handling 
information 


R13 


















FORTRAN 
interrupt handling 
information 








J:;§i§:Mii|::S^:-?^JS:i?i! 




.- 




R12 




















4 


Call COBOL from PL/I (IBMBIEC) 

The PL/I program will contain a call to the interlanguage routine 
IBMBIEC, which: 

1. Sets up another interlanguage VDA, points ZCTL to this 
VDA, and places the old value of ZCTL's pointer in the 
VDA. 

2. Stores R1 3 in the new VDA. 

3. Issues a SPIE so that error handling will be as requested 
by PL/I program. 

Control IS then returned to compiled code, which then calls 
the COBOL routine. 




IBMBILC1 






ZCTL 






VDA (Second) VDA (First) 
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/* 


y^ 
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y^ 
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FORTRAN 
interrupt handling 
information 


R13 


R13 








FORTRAN 


— -> «-w ■ >. 

R12 


interrupt handling informati 





























1 section by the PL/I interlanguage 
}s are initially zero. 




IBMBILC1 








IBMBILC1 






ZCTL 










Final situation 

ZCTL is retained until program is completed. 


8 






Zero 






.^ 


Address of ZCTL 






Zero 


Zero 
i 






X 












\ \ 
COBOL FORTRAN 
flag flag 




















IBMBILC1 






ZCTL 






VDA (First) 




FORTRAN returns to PL/I (IBMBIEF) 

When control returns from a FORTRAN procedure, a call is made 
to the interlanguage communication routine IBMBIEF, which; 

1 . Moves the pointer in the VDA to the first word of ZCTL. 

2. Issues a PL/I SPIE macro. 

3. Issues a PL/I STAE macro leaving the previously-stacked 
FORTRAN STAE for possible future use. 

4. Returns control to compiled code. 
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/IBIEF) 

( the interlanguage communications 
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^ 






[for zero pointer in IBMBILC1. 
VDA. 




X 




■:■ 

FORTRAN 
interrupt handling 
information 




R13 


-language VDA, and IBMBILC1 
MBILC1. Saves R12 in ZCTL, 










D initialize FORTRAN SPIE 
as required, 
which calls FORTRAN 






R12 




-— ....^ 


1BIEP) 

declared with the option 
piled inside an encompassing 
irocedure is the one called by 




1BMBILC1 


ZCTL 






VDA (First) 




PL/I returns to FORTRAN (IBMBIEP) 

When the required PL/I procedure is finished, it returns control 
to the encompassing procedure. The encompassing procedure 
calls the interlanguage routine IBMBIEP, which issues a SPIE 
macro instruction to restore the error-handling situation to that 
of the calling routine. The information for the SPIE macro 
instruction is retrieved from the interlanguage VDA. The 
current PL/I STAE is canceled, leaving the previously stacked 
FORTRAN STAE in control. 

The interlanguage routine returns control to the PL/I encompas 
sing procedure, which then returns control to the FORTRAN 
program. 
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procedure calls the inter- 
ie IBMBiEP which" 


FORTRAN 
interrupt handling 
information 


R13 


F either FORTRAN or COBOL 










ft, restores registers. 






FORTRAN 
interrupt handling 
information 


: and stores interrupt handling 
iram in interlanguage VDA. 


^ 


)mpassing program, which calls 


R12 
















:C) 




IBMBILC1 






ZCTL 






VDA (Second) VDA (First) 




COBOL returns to PL/i 

The COBOL program returns to the PL/I program, which 
immediately calls the interlanguage routine IBMBIEC This 
routine rearranges the chain by placing the word in the most 
recent VDA in the first word of ZCTL. It then issues a SPIE 
macro instruction to restore the PL/I error-handling situation. 

PL/1 compiled code then continues. 
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call to the interlanguage routine 
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/* 
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ige VDA, points ZCTL to this 
lue of ZCTL's pointer in the 
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FORTRAN 
interrupt handling 
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Figure 13.6. Example of chaining sequences (PL/I principal procedure) 
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Initial situation 

IBMBILC1 



Zero Zero 



FORTRAN flag 



Situation on return 
IBMBILC1 ZCTL 



- 


♦ 


Address of ZCTL 
















'~~~~ — _^— -• 



Initial situation Situation on return 

PARTITION 



Exists for use 
if PLISAhas 
been called 



Dummy DSA 



FORTRAN principal procedure calls PL/I 



ZCTL 




VDA (First) 


- 


It 


R13 




FORTRAN 
interrupt 
handling 
information 


FORTRAN 
interrupt 
handling 
information 




R12 









Dummy DSA 



Encompassing DSA 



Required DSA 



PL/I calls FORTRAN 



VDA (Secondl 



VDA (First) 



FORTRAN 
interrupt 
handling 
information 



W: 



FORTRAN 
interrupt 
handling 
information 



Dummy DSA 



Encompassing DSA 



Required DSA 



FORTRAN calls PL/I 



VDA (Second) 



VDA (First) 



FORTRAN 
interrupt 
handling 
information 



FORTRAN 
interrupt 
handling 
information 



FORTRAN 
interrupt 
handling 
information 



Dummy DSA 



Encompassing DSA 1 



Required DSA 1 



Encompassing DSA 2 



Required DSA 2 



Figure 13.7. Examples of chaining sequences (FORTRAN principal procedure) 
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Handling_ the INTER__Option 



When the INTER option is specified, the U. 
programmer gets neither normal PL/I 
interrupt handling nor the normal interrupt 
handling for the other language. Instead, 5. 
he gets PL/I error handling of those 
interrupts which are left to the system by 
the non-PL/I languages. To allow for this, 
the type of interrupt has to be analyzed 
after it has occurred and passed to the 
correct error handling routines. 

Interrupts are analyzed by subroutines 
of the interlanguage housekeeping routines 
known as traps . The interlanguage 
housekeeping routines save the PICA 
addresses for the calling language and the 
called language and issue a SPIE that will 
pass control to the trap code. When an 
interrupt occurs control is passed to the 
trap, which analyzes the interrupt. The 
trap code issues the appropriate SPIE to 
restore the required error handling 
situation and then alters addresses so that 
normal return from the interrupt will 
result in control being passed once more to 
the interlanguage housekeeping trap 1. 

routine. It then forces an interrupt and 
the interrupt is handled by the appropriate 
language. When control returns to the trap 
a further SPIE is issued so that control 2. 
returns to the trap should further 
interrupts occur. The method used for each 
module is described below. 



When an interrupt occurs with the 
INTER option 

When a STOP or STOP RUN statement is 
executed 

For PL/I and FORTRAN only, when the 
environment is discarded and the 
termination routine entered 



COBOL WHEN CALLED FROM PL/I (IBMBIEC) 



Before Entry to_CQB OL_P r ogr a m 

IBMBIECA - Entry point for COBOL error 
handling 

IBMBIECB - Entry point for INTER error 
handling 

When IBMBIEC is called before the COBOL 
program, the following must be done: 



Test to see if this is the first 
interlanguage call; if so, set COBOL 
flag in IBMBILCl and set up ZCTL. 

Acquire interlanguage VDA and store 
register 12 and register 13 in the 
VDA. Write null PICA information in 
ZCTL. 



STOP and STOP RUN Statements 



PL/I and FORTRAN STOP statements and COBOL 
STOP RUN statement cause certain problems 
because various save areas may be bypassed. 
The methods adopted to solve these problems 
are discussed in the individual description 
of the modules. 



If INTER option not specified (i.e., 
entry point IBMBIECA) , issue SPIE 
macro instruction so that errors will 
be handled by the supervisor. Return 
to compiled code. 

If INTER option is specified (entry 
point IBMBIECB) , issue new SPIE macro 
instruction and return so that 
interrupts will be passed to the trap 
code. 



Housekeeping Module Descriptions 



As the differences between individual 
interlanguage housekeeping modules are 
considerable, a detailed description of 
each module follows. The description 
covers the following situations: 

1. When the associated language routine 
is called 

2. When the associated language routine 
returns control 



On Return from COBOL Program (IBMBIECC) 



The following actions take place on return: 

1. A SPIE macro instruction is executed, 
which results in the the PL/I error 
handling scheme being restored. 

2. The first word of the interlanguage 
VDA and the VDA flags are moved into 
the first word ZCTL, and the VDA is 
freed. 
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Save area for 
CALLER'S CALLER 



Save area for CALLER 



Save area for 
INITIALIZATION/ 
TERMINATION 
ROUTINE PL/I or 
FORTRAN 



Save areas are re-chained 
so that the environment 
is not discarded until 
the caller is terminated. 
Note: additional save 
areas are introduced. 
See figures 13.9 & 13.10 
for details. 



Save area for 

PL/I or FORTRAN 



Figure 13.8. 



The concept of save area rechaining (see figures 13.9 and 13.10 for 
details) 
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Caller's caller 



I 



Save area 1 
(Register 14 in this save area points to 
the tail code in IBMBIEF. For normal 
return the tail code calls IBCOM in 
the FORTRAN library to discard the 
FORTRAN environment.) 



I 



Caller's 



I 



FORTRAN routine 



Figure 13.9. Rechaining of save areas when FORTRAN is called from PL/I and the 
FORTRAN environment needs initializing 
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r 



Caller's Caller 
(replaced in this position 
by tail code in IBMBIEP 
R14 value restored from 
ghost save area) 



1 



Save area 2 
(passes control to tail 
code in IBMBIEP 



Dummy PSA 
(Save area for PL/I 
initialization/termination 
routine) 



Save area 1 
Passes control to tail 
code in IBMBIEP (entered 
after FORTRAN STOP) 



Caller's Caller adapted 
(register 14 value is altered 
to pass control to tail 
code in IBMBIEP) 




PL/I 
Encompassing Procedure DSA 



PL/I 
Required Procedure DSA 



Figure 13.10. 



Rechaining of save areas when PL/I is called from FORTRAN or COBOL 
and the environment requires initialization 
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Action on Interrupt in COBOL with INTER 



If the INTER option is not specified, all 
program checks will be handled by the 
supervisor in the usual manner. If the 
INTER option is specified and the program 
has been compiled with a request for the 
COBOL interrupt handler not to be called, 
the following takes place. 

1. During the first invocation of 
IBMBIEC, a SPIE macro instruction is 
issued, which results in interrupts 
being passed to entry address in the 
trap. 

2. When an interrupt occurs, register 12 
and register 13 are restored thus 
restoring the PL/I environment. 

3. A DSA is acquired for IBMBIEC in LWS. 
The address of the interrupt, in the 
second word of the PSW, is saved in 
this DSA and replaced by the address 
of another entry address in the trap. 
For underflow interrupts, the four 
bytes preceding the point of interrupt 
are also copied and placed before the 
trap in case the error handler needs 
to examine them. The trap acts as the 
return address for the PL/I error 
handler. 

4. Flags are set in the TCA and DSA to 
indicate that it is possible for an 
abnormal GOTO to occur in a PL/I on- 
unit . 



original INTER SPIE is reissued, and the 
registers and PIE are restored. The 
original interrupt address is set in the 
PSW. Control is returned to the supervisor 
which passes control to the address in the 
PSW with the correct register values 
restored. 



Zerodivide On-Units 



When used with certain COBOL compilers, 
normal return from a zerodivide on-unit 
will result in a data exception. This is 
because a ZAP instruction is executed after 
the divide on computational-3 data. The 
ZAP instruction picks up an invalid field. 



Handling STOP RUN statements 



ANS COBOL STOP RUN Statements are handled 
by a COBOL routine which passes control to 
a specified address. When IBMBIEC is 
called before entry to a COBOL program this 
address is set to the tail code in IBMBIEC. 
This tail code dechains all save areas or 
routines that were entered after the PL/I 
caller and then executes a PL/I STOP 
statement. 



FORTRAN WHEN CALLED FROM PL/I (IBMBIEF) 



5. A SPIE macro instruction is issued to 
transfer the program check exit to the 
PL/I error- handling routines whose 
address is held in the TCA appendage. 

Return from interrupt; If there is a GOTO 
out of a PL/I on-unit, control passes to 
the abnormal GOTO subroutine, this is 
because flags indicating an abnormal GOTO 
situation are set up by the trap code. The 
abnormal GOTO subroutine analyzes these 
flags and passes control to IBMBIEC which 
handles any necessary housekeeping 
problems. 

If the return is normal,, the PL/I error 
handling routines return control to the 
address in the second word of the PSW. 
This word has been altered by code in the 
trap, and further trap code in IBMBIEC is 
entered. 

It is necessary to return to the point 
of interrupt in the COBOL program without 
changing any of the register values and 
this can only be done via the supervisor. 
A new SPIE is set to point to further trap 
code and an interrupt forced. The program 
is now in an interrupted state, the 



When FORTRAN is called by PL/I, IBMBIEF is 
entered immediately before and immediately 
after the execution of the FORTRAN program. 
The processing done before entry to the 
FORTRAN program depends on whether the 
INTER option is specified. Entry point 
IBMBIEFA handles calls without the INTER 
option. Entry point IBMBIEFB handles calls 
with the INTER option. 



Before Entry^tg the_FORTRAN Program 



Entry Point IBMBIEFA FORTRAN error handling 

Entry Point IBMBIEFB INTER error handling 

Before the call to FORTRAN, IBMBIEF does 
the following: 

1. Tests the flags in IBMBILCl to 
discover if this is the first 
interlanguage call, if it is the 
first call, it sets up ZCTL and sets 
the FORTRAN flag in IBMBILCl. If it 
is not the first call, it tests to see 
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2. 



whether the FORTRAN flag is set in 
IBMBILCl and sets the FORTRAN flag if 
it is not already set. 

IBMBIEF stores register 13 in the 
interlanguage VDA, thus saving the 
PL/I environment. 



function entry point) the parameter 
list passed by PL/I is examined, and 
the values are moved from registers in 
which they were placed by the FORTRAN 
routine, to the location expected by 
PL/I. 



3. If the FORTRAN environment has not 
previously been set up, calls the 
FORTRAN initialization routine. This 
routine sets up the program check exit 
so that program interrupts will be 
handled by the FORTRAN error handling 
method. The FORTRAN error data is 
stored in ZCTL. Save area one (SAD is 
then inserted in the save area chain. 
The resulting save area chaining is 
shown in figure 13.9. 

4. IBMBIEF acquires an interlanguage VDA. 
Points the first word of ZCTL to this 
VDA, taking the value previously in 
the first word of ZCTL and placing it 
in the first word of the VDA. (This 
places the new VDA at the head of a 
chain starting from ZCTL. ) 

5. If INTER option is not specified, 
issues a FORTRAN SPIE macro 
instruction from ZCTL, sets program 
mask to • 2* , and returns to compiled 
code. 

6. If INTER option is specified, a SPIE 
macro instruction is issued that will 
result in control being passed to the 
trap should an interrupt occur. The 
program mask is reset to 'E' in case 
it was changed by the FORTRAN 
initialization routine. 



Action on Return from FQRTRAN__Program 
(IBMBIEFC aiiH IBMBIEFD) 



When return is made from the FORTRAN 
subroutine, PL/I compiled code immediately 
makes a call to the FORTRAN interlanguage 
routine. If the FORTRAN routine may have 
been used as a function, entry point 
IBMBIEFD is used. Otherwise, entry point 
IBMBIEFC is used. The module IBMBIEF does 
the following: 

1. A SPIE macro instruction is issued 
that resets the program check exit to 
the PL/I error-handling modules, and 
the program mask is set to 'E'. 

2. The first word of the interlanguage 
VDA is placed in the first word of 
ZCTL. The VDA flags inserted in ZCTL 
and the VDA freed. 

3. For entry point IBMBIEFD (the FORTRAN 



Action on Interrupt in FORTRAN 



If the INTER option is not specified, the 
action on any interrupt that occurs in the 
FORTRAN program will be that specified in 
the FORTRAN error-handling scheme. 
However, if the INTER option is specified, 
all program checks that are not handled by 
FORTRAN error-handling are passed to the 
PL/I error-handling modules. 

The FORTRAN error-handling scheme is 
used after the following interrupts have 
occurred: 

1. Specification (other than for invalid 
instruction address) 

2. Fixed-point divide 

3. Decimal divide 

H . Exponent overflow 

5. Exponent underflow 

6. Floating-point divide 

All other program checks are handled by the 
PL/I error handler. 

If the INTER option is specified, when 
an interrupt occurs the following takes 
place: 

1. When control is passed by the 
supervisor to the trap, the type of 
interrupt is discovered by examining 
the PSW. If the interrupt is one of 
the types that can be handled by 
FORTRAN, the normal FORTRAN 
environment is established and the 
FORTRAN error handling module invoked. 

2. If it is not the type of interrupt 
that can be handled by FORTRAN, 
register 12 is restored from ZCTL and 
13 from the latest interlanguage VDA, 
thus restoring the PL/I environirent. 

3. The address of the interrupt is taken 
from the second word of the PSW and 
stored in the DSA. The second word of 
the PSW is then replaced by an entry 
address in the trap in IBMBIEF. 

4. Flags are set in the TCA and DSA to 
indicate that it is possible for an 
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abnormal GOTO to occur in a PL/I on- 
unit. 

5. A SPIE macro instruction is then 
issued to restore the PL/I error- 
handling situation. A branch is then 
made to the PL/I error handler. 

Return from interrupt; If there is a GOTO 
out of a PL/I on-unit, control passes to 
the abnormal GOTO subroutine, this is 
because flags indicating an abnormal GOTO 
situation are set up by the trap code. The 
abnormal GOTO subroutine analyzes these 
flags and passes control to IBMBIEF which 
handles any necessary housekeeping 
problems. 

If the return is normal, the PL/I error 
handling routines return control to the 
address in the second word of the PSW. 
This word has been altered by code in the 
trap, and further trap code in IBMBIEF is 
entered. 

It is necessary to return to the point 
of interrupt in the FORTRAN program without 
changing any of the register values and 
this can only be done via the supervisor. 
A new SPIE is set to point to further trap 
code and an interrupt forced. The program 
is now in an interrupted state, the 
original INTER SPIE is reissued, and the 
registers and PIE are restored. The 
original interrupt address is set in the 
PSW. control is returned to the supervisor 
which passes control to the address in the 
PSW with the correct register values 
restored. 



Termination of Caller 



When the routine that called FORTRAN is 
terminated, control is passed to the 
address held in the register lU save area 
in save area one. This address is the 
address of the tail code in IBMBIEF. If 
the return is normal, the tail code calls 
IBCOM in the FORTRAN library to discard the 
FORTRAN environment. It then frees ZCTL 
and returns control to the caller's caller. 



STOP Statements 



If control returns to the tail code because 
of a FORTRAN STOP Statement the tail code 
discards any save areas that may have been 
bypassed by the FORTRAN STOP statement and 
finally executes a. PL/I STOP statement 
which terminates the program. 



PL/ I CALLED FROM COBOL OR FORTRAN 
(IBMBIEP) 



As with the other interlanguage 
communication routines, IBMBIEP is called 
immediately before and immediately after 
the program that is to be executed. 
However, the interlanguage housekeeping 
routine cannot be called direct from the 
COBOL or FORTRAN routine, because the 
existence of such a routine is unknown to 
COBOL or FORTRAN. To overcome this problem, 
an encompassing routine is generated with 
the same entry name as the PL/I routine. 
This encompassing routine is called by 
COBOL or FORTRAN and in turn calls the 
interlanguage housekeeping routine and the 
required PL/I routine. 

Although the names of both PL/l 
procedures are the same, the encompassing 
routine gets control when called from COBOL 
or FORTRAN. This happens because no ESD 
records are generated for the interlanguage 
entry points of the required PL/'l program, 
code for a PL/I encompassing routine is 
shown in figure 13.5. Figure 13. U shows 
the calling sequence. 



Before Entry to PL/I Program (IBMBIEPA) 



Before a call is made to the required PL/I 
program, IBMBIEP does the following: 

1. Tests to see if the PL/I environment 
has already been initialized, by 
examining whether the COBOL or FORTRAN 
flag in IBMBILCl is set. 

2. If the COBOL of FORTRAN flag is set, 
this means that a previous 
interlanguage call has been made, and 
as the call must have been made either 
to or from PL/I, the PL/I environment 
must have been set up. If it is 
established that the PL/I environment 
exists, register 12 is restored from 
ZCTL. A SPIE macro instruction is 
issued so that program checks are 
handled by the PL/I error handler. 
The address of the old PICA is stored 
in the interlanguage VDA. Control 
returns to the encompassing routine. 

3. If neither the COBOL nor the FORTRAN 
flag is on, PL/I is being called for 
the first time by a procedure in a 
program whose principal procedure is 
COBOL or FORTRAN. The following action 
is taken: 

a. IBMBIEP issues a GETMAIN macro 
instruction and sets up ZCTL in 
the storage acquired. 



2He 



b. The PL/I initialization routine, 
IBMBPIR is called. It sets up the 
PL/I environment and returns 
control to an address in IBMBIEP 
that it was passed by IBMBIEP. 
IBMBIEP then stores the registers 
of IBMBPIR in the dummy DSA. 

c. The chaining of save areas is then 
altered, so that the dummy DSA 
(the save area used by IBMBPIR) is 
above the calling program's 
standard save area. The result of 
this is that, when the 
encompassing routine is complete, 
return is made to the COBOL or 
FORTRAN calling routine rather 
than to IBMBPIR. Thus the PL/I 
termination routine is not entered 
and the PL/I environment is 
retained until the COBOL or 
FORTRAN calling program is 
completed. Two further save areas 
are also inserted into the chain. 
These result in control being 
passed to tail code in IBMBIEP, 
which handles housekeeping 
problems. The save area of the 
caller* s caller is also altered so 
that the register 14 value also 
points at tail code in IBMBIEP. 
The true register 14 value is 
saved in ZCTL in storage known as 
the ghost__saye_ ar ea . The 
resulting save area chain is shown 
in figure 13.10. Action taken 
when the calling routine is 
terminated is described below, 
under the heading "Termination of 
PL/I Environment" . 

4. A DSA for the encompassing routine is 
acquired. 

5. The address of the new DSA is placed 
in the register slot of the dummy 
DSA. 



returned value may be required, the entry 
point IBMBIEPD is used and the returned 
value is loaded into the required position. 
In other situations, the entry point 
IBMBIEPC is used. The module resets the 
program mask by issuing SPIE macro 
instruction to restore the calling 
routine's program check exit, the address 
of which has been stored in the 
interlanguage VDA. 



Inte r rupt Handling 



When PL/I is called by COBOL or FORTRAN, 
error handling is carried out in the normal 
PL/I manner. The SPIE macro instruction is 
issued by IBMBPII when the PL/I environment 
is first set up. For calls after the 
first, the SPIE macro instruction is issued 
by IBMBIEP. 



Termination of PL/I Environment 



The PL/I environment is discarded when the 
caller's caller is terminated. In a normal 
situation control is returned by the caller 
to the address held in the register 14 save 
area of the caller's caller. This address 
was altered during the initialization of 
the PL/I environment to point to tail code 
in IBMBIEP. This code receives control and 
rearranges the save area chaining. It then 
returns to IBMBPIR whose registers are in 
the dummy DSA. The PL/I program is then 
terminated and control returns to save area 
2. This again points to tail code in 
IBMBIEP. This tail code restores the 
correct register 14 value of the caller's 
caller from the ghost save area and returns 
to the caller's caller. 



Control is then returned to compiled 
code in the encompassing routine. 



STOP and STOP RUN Statements 



Action after the_PL/I_Program. is 
Completed 



Entry point IBMBIEPC - normal 

Entry point IBMBIEPD - return value 
expected 

IBMBIEP is called at the end of the PL/I 
routine by the encompassing routine 
generated by the compiler. If the calling 
program is FORTRAN, a returned value may be 
expected in register or one or more of 
the floating-point registers. When a 



For a PL/I STOP statement the action is 
carried out in a normal manner and flags in 
save area one indicate that an abnormal 
GOTO situation exists. The situation is 
analyzed by the abnormal GOTO subroutine 
and control is passed to tail code whose 
address is held in save area one. 

For a FORTRAN STOP statement when the 
calling program is FORTRAN the situation 
depends on how many levels of FORTRAN 
precede PL/I. If the caller is the highest 
level of FORTRAN prior to PL/I, control 
will be passed to save area_ one and tail 
code entered to carry out the necessary 
housekeeping. If there is more than one 
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level of FORTRAN, control will pass to the 
highest active level of FORTRAN and the job 
will be terminated without carrying out 
PL/I program termination. 

A COBOL STOP RUN statement will be 
analyzed by IBMBIEC which will execute a 
PL/I STOP statement. 



Handling Data Aggregate Arguments 



In order to communicate effectively between 
COBOL and PL/I, and FORTRAN and PL/I, a 
method of handling data aggregate arguments 
is necessary, because the three languages 
hold data aggregates in different ways.. 



ARRAYS 



binary item has a fullword alignment 
requirement; the character has a byte 
alignment requirement. In PL/I, the 
structure would be declared: 

DCL 1 A, 

2 B CHAR (1), 

2 C FIXED BINARY (31,0); 

and would be held thus: 

J. 



I B I C I 

L . J 

In COBOL, the structure would be declared: 



01 A. 
02 
02 



B, PICTURE X, DISPLAY. 

C, PICTURE S9(9), COMPUTATIONAL. 



and would be held thus: 



B I 3 unused bytes 



Arrays as such are not used in COBOL. The 
use of OCCURS in structures does, however, 
have a similar effect. However, PL/I 
structures of arrays and COBOL structures 
using OCCURS are both held in row-major 
order. In FORTRAN, arrays are held in 
column-major order. Thus, in a two- 
dimensional array, the element known in the 
FORTRAN array as (2,1) will become (1,2) in 
the PL/I array. 



STRUCTURES 



Structures are not used in FORTRAN. In 
COBOL the alignment requirements are met 
differently from PL/I. Full details of the 
differences in mapping are given in the 
language reference manual for this 
compiler. 

COBOL structures are mapped as follows, 
working from the start, each item is 
aligned to its required bounda/ry in the 
order in which it is declared, the 
structure starting on a doubleword 
boundary. 

PL/I structures are mapped by a method 
that minimizes the unused bytes in the 
structure. Basically, the method used is 
first to align items in pairs, moving the 
item with the lesser alignment requirement 
as close as possible to the item with the 
greater alignment requirement. The method 
is described in full in the language 
reference manual. 

Take, for example, a structure 
consisting of a single character and a 
fullword fixed binary item. The fullword 



METHODS USED TO HANDLE DATA AGGREGATE 
ARGUMENTS 



The method used in handling data aggregates 
is to create dummy arguments of the correct 
format and let the called routine use the 
dummy. The values in the dummy are then 
assigned to the original argument when the 
execution of the called program is 
completed. 

If the data aggregates are not 
adjustable, the mapping will be done during 
compilation and both the PL/I and the COBOL 
or FORTRAN mapping are produced. If the 
data aggregates are adjustable, the mapping 
is done during execution. Before the 
execution of the call to a program in 
another language, the data is transferred 
into the correctly mapped aggregate, which 
will be held in PL/I temporary storage. 
The values are reassigned to the original 
data aggregate after execution of the 
interlanguage program. 

The assignment of data between the dummy 
and the argument is done by compiled code. 



NOMAP, NOMAPIN, AND NOMAPOUT OPTIONS 



The NOMAP, NOMAPIN, and NOMAPOUT options 
can be used by the programmer to specify 
that data aggregates will not be remapped 
and placed in dummy arguments. 

When NOMAP is specified, or when both 
NOMAPIN and NOMAPOUT are specified, the 
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dummy is not generated at all, and the 
structure or array is passed as it stands. 

When only NOMAPIN is specified, a dummy 
is created, but it is not initialized with 
the values of the aggregate being passed. 
However, on return from the COBOL or 
FORTRAN routine^ the data in the dummy is 
placed in the data aggregate that is being 
passed. 

When only NOMAPOUT is specified, a dummy 
is created, and the data from the data 
aggregate is moved into the dummy. When 
control is returned to the calling program, 
however,, the data from the dummy is not 
moved into the data aggregate that was 
passed. 



CALLING SEQUENCE 



When PL/I calls COBOL or FORTRAN passing 
data aggregates as arguments, the sequence 
of events is: 

1. Handle data reassignment to dummy by 
compiled code. 

2. Call interlanguage housekeeping 
routine. 

3. Call COBOL or FORTRAN routine, 

U. Call interlanguage housekeeping 
routine. 

5. Assign data in dummy to real argument, 
by .means of compiled code. 

When COBOL or FORTRAN calls PL/ I, the 
sequeYice of events is : 

1. The COBOL or FORTRAN routine calls the 
encompassing PL/I routine. 

2. The encompassing PL/I routine: 

a. Calls the interlanguage 
housekeeping routine. 

b. Sets up the necessary dummy data 
aggregate argument by compiled 
code. 

c. Calls the required PL/I routine. 

d. Reassigns the data from the dummy 
by compiled code. 

e. Calls the interlanguage 
housekeeping routine. 

f . Returns to the original calling 
routine. 



It is necessary to make calls in this 
order, because the data mapping must be 
done in a PL/I environment. 



ASSEMBLER Option 



The optimizing compiler provides a facility 
to simplify calling assembler language 
routines from PL/I. This consist of 
setting up an argument list that contains 
the addresses of all items passed rather 
than the addresses of locators. 

When an entry point is declared as 
OPTIONS (ASSEMBLER) , parameter lists passed 
to the entry point are set up to contain no 
locator addresses. The addresses of any 
areas, arrays, strings, or structures are 
passed directly in a parameter list. (For a 
call to a PL/I routine, the parameter list 
would contain the address of locators for 
these data types. This is because the 
called routine might require information on 
the length or bounds of the data and this 
is accessible through the locator. See 
chapter 4 for details.) 

The ASSEMBLER option does not provide 
facilities for automatically overriding 
PL/I interrupt handling, nor does it allow 
PL/I routines to be called from assembler 
language. If the programmer requires these 
facilities, he must either provide the 
necessary code himself or use the COBOL 
option. The COBOL option without the INTER 
option provides complete facilities for 
calling, or being called by, assembler 
routines. However, its use involves the 
overhead of calls to the PL/I library 
interlanguage communication routines. 

Full instructions on how to use PL/I 
with assembler language are given in the 
programmer's guide for this compiler. 



COBOL Option in the Environment Attribute 



A separate interlanguage coirmunication 
facility offered by the compiler is the use 
of the COBOL option in file declarations. 
This option allows data sets created by 
COBOL programs to be read by PL/I programs 
and allows data sets to be created by PL/I 
programs in a format that is usable by 
COBOL programs. Interchange of data sets 
presents no problems, unless structures are 
used in the data set. If structures are 
used, their mapping may be different. (See 
above, under the heading "Handling Data 
Aggregate Arguments.") When structures are 
involved and the mapping is not known to be 
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the same, both COBOL and PL/I structures 
are mapped, and compiled code transfers the 
data between structures ininiediately after 
reading the data for input, and immediately 
before writing the data for output. 

During compilation,, the compiler 
examines the record variable to see if any 
structures are involved. If no structures 
are involved, no further action need be 
taken. If structures are involved, a test 
is then made to see if the mapping of the 
structure or structures will be the same in 
COBOL and PL/I. If the compiler can 
determine that the mapping will be the 
same, then no action is required. If the 
compiler cannot determine that the mapping 
will be the same or if the structure is 
adjustable, both structures will be mapped. 
Adjustable structures will be mapped during 
execution by the resident library 
structure-mapping routines. Other 
structures will be mapped during 
compilation. 



When re-formatting of data is necessary, 
the following actions take place when a 
record I/O statement involving a file with 
the COBOL option is executed. 



INPUT: 



The data is read into a structure 
which has been mapped using the COBOL 
mapping, algorithm and assigned to a 
PL/I mapped structure. 

OUTPUT : 

Before the output takes place, the 
data in the PL/I structure is assigned 
to a structure mapped for COBOL,. The 
output to the data set then takes 
place from the second structure. 

The data assignment is carried out by 
compiled code in all circumstances. 
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COMPILED CODE 

Relies on library modules for 
executing code that is sensitive to 
differences between multitasking 
and non-multitasking. 



BASE LIBRARY SYS1.PLIBASE 

Contains modules to handle all 
library functions in a non- 
multitasking situation. 



MULTITASKING LIBRARY SYSL.PLITASK 

Contains modules that handle all 
multitasking-sensitive operations. 

These modules have the same link- 
edit names as parallel modules in 
the base library. 



Figure 14.1. Multitasking is implemented by use of a multitasking library 
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Chapter 14: Multitasking 



Introduction 



The .Concept_of ,_t.he Cont.rol_ Task 



Multitasking allows the PL/I programmer to 
make use of system multiprogramming 
facilities within a single jobstep. The 
PL/I main procedure and certain other PL/I 
procedures are attached as tasks, and 
compete for the facilities of the CPU. 



All features of the PL/I language that 
are implemented differently for 
multitasking and non-multitasking programs 
are handled by routines in the OS PL/I 
Resident and Transient Libraries. The non- 
multitasking routines are held in the 
partitioned data set SYSI.PLIBASE; the 
multitasking routines are held in the 
partitioned data set SYSl.PLITASK. When a 
multitasking program is link-edited, the 
automatic call library must be identified 
by sequential SYSLIB DD statements 
specifying first SYSl.PLITASK and then 
SYSI.PLIBASE. 



subroutines that have the same function 
in both the multitasking and the non- 
multitasking libraries have the same link- 
edit name (see chapter 3). consequently, 
no special calls are required in compiled 
code. If the program uses multitasking, the 
multitasking version of the library module 
will be link edited, provided that 
SYSl.PLITASK is specified before 
SYSI.PLIBASE. Where a module is required 
only for multitasking programs, it is 
addressed from the TCA. The results of 
attempting to access such a module in a 
non-multitasking program are unpredictable. 
The concept of the multitasking library is 
shown in figure 14.1. 



The use of a special multitasking 
library to handle all code that is affected 
by multitasking minimizes the effect on 
compiled code. Special action* is required 
only for a CALL statement with any of the 
multitasking options, and for the epilogue 
of a block that contains a CALL statement 
with multitasking options. Otherwise, the 
code generated for a multitasking program 
is exactly the same as the code generated 
for a non-multitasking program. The TASK 
option on a procedure statement, necessary 
with some compilers, is ignored by the 
optimizing compiler. 



To implement PL/I multitasking, the 
facilities offered by the operating system 
control program have to be used in a manner 
that meets the specifications of the PL/I 
language. Certain facilities offered by 
PL/I, notably the ability of any task tc 
change the priority of any other task, are 
not directly available in the system. 
Consequently, an interface is used between 
the system facilities and PL/I tasks. This 
interface takes the form of a control task. 

The control task has all PL/I tasks 
attached as direct subtasks and always has 
a higher priority than any PL/I task. 
Certain functions are always carried out 
within the control task. These functions 
are: 

1. Attaching and detaching of tasks 

2. Accessing or altering COMPLETION or 
PRIORITY values 

3. Modification of event variables 
(except for STATUS pseudovariable) 

H . Generating PL/I dumps 

5. Access to lOCBs (see chapter 8) in 
certain conditions. 

The first two are carried by the control 
task because of the demands of the system 
control program. The third is carried out 
by the control task because it is important 
that no two tasks try to access the event 
variable chain at the same time. 

The apparent and actual hierarchy of 
tasks is shown in figure 14.2. The 
functions executed in the control task are 
shown in figure 14.3. 

Throughout most of the execution of a 
PL/I multitasking program, the control task 
is in a wait state and the various PL/I 
tasks are competing for the facilities of 
the CPU. The control task waits on an ECB 
list that contains an ECB (event control 
block) for each PL/I task and an ECB known 
as the task- end ECB that is used when 
terminating a task. Whenever any of the 
functions that must be carried out in the 
control task are required, the ECB 
associated with the requesting task is 
posted with a request code and the task 
goes into a wait state, waiting on an ECB 
that is posted complete when the requested 
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function has been executed in the control 
task. 



control task in the list that follows the 
POST ECB. 



Communication between Tasks 



As explained above, there is no 
communication between PL/I tasks except 
through the control task. Communication 
between the control task and the PL/I tasks 
is made through control blocks known as 
tasking appendages. Every PL/I task has a 
tasking appendage, which is addressed from 
and is contiguous with the TCA of the task. 

As shown in figure 14.4, every tasking 
appendage is headed by an ECB, followed by 
two fullwords for parameters, followed by 
another ECB. 

The first ECB in the tasking appendage 
is known as the POST ECB, and is one of the 
ECBs in the ECB list on which the control 
task waits. The second ECB is known as the 
WAIT ECB and is the ECB on which the task 
waits while a function is carried out in 
the control task. 

When code within a subtask requires a 
service to be done in the control task, it 
posts the POST ECB with a completion code 
to identify the service required, and waits 
on its WAIT ECB. The WAIT ECB will be 
posted complete when the requested action 
has been completed in the control task. 

The completion codes that are used to 
post the POST ECB are: 



COMPLETION PSEUDOVARIABLE 
POSTCODE 

EVENT ASSIGNMENT POSTCODE 

PRIORITY PSEUDOVARIABLE 
POSTCODE 

I/O EVENT COMPLETION POSTCODE 

WAIT TERMINATION POSTCODE 

EXECUTE IN CTRL TASK 

DEDICATE CONTROL TASK ROUTINE 

LIBERATE CONTROL TASK ROUTINE 

ATTACH A TASK 

END OF TASK 

TERMINATE SUBTASK 

TERMINATE SUBTASK 



X'O' 

X'8' 

X'C 

X»10' 

X«14' 

X'18* 

X'lC 

X*20' 

X*2H* 

X«28' 

X*2C* 



Any parameters required are passed to the 



Holding the Priority of _t he_Tas k 



The control program retains the priority of 
a task in an associated TCB (task control 
block). At the PL/I level, however, the 
priority is held in a task varia ble . This 
allows the priority of the task to be set 
even when the task is inactive, and also 
allows reference to the task by the 
program. Each task has a task variable 
which is connected to the TCB through the 
tasking appendage. The address of the 
associated tasking appendage is placed in 
the task variable when the task is 
attached. 

When a change in the priority of a task 
is requested, the priority is always 
changed in the task variable. If the task 
variable is active, the priority is also 
changed in the TCB. 

Also associated with a task is an event 
variable. The event variable is set 
"complete" when the task is terminated. 

All tasks have associated event and task 
variables. If none are specified by the 
programmer, dummy variables are provided 
during task attachment. These dummies are 
held in the task's own workspace, and are 
discarded when the task is terminated. 



Multitasking Housekeeping 



Multitasking housekeeping is similar to 
non-multitasking housekeeping. Every task 
has its own TCA and other blocks in the 
program management area, as described in 
chapter 5 . 

The major differences are that the TCA 
for each task has a control block known as 
the tasking appendage, and that DSA 
chaining between tasks cannot follow the 
rules of calling procedures. 

As shown in figure 1U.6, the chaining of 
DSAs is arranged so that the dummy DSA of 
the attached task is in the chain but the 
DSA of the attaching procedure is not. 
This protects the attached tasks from any 
changes in establishment of on-units that 
may occur in the block that attached the 
task. In order that error handling and 
other functions using the backchain may 
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PL/I PROGRAM 
X:PROC; 

CALL Y TASK (T1) EVENT (El); 

Y:PROC; 

CALL Z TASK (T2) EVENT (E2); 
Z:PROC; 

ENDZ; 
END Y; 
ENDX; 



PL/I HIERARCHY 



ACTUAL HIERARCHY 

(as recognised by operating system) 



CONTROL TASK 



MAJOR TASK 



Y(taskTI) 
SUBTASK OF 
MAJOR TASK 



MAJOR TASK 
SUBTASK OF 
CONTROL TASK 



Y(taskTI) 
SUBTASK OF 
CONTROL TASK 



Z (Task T2) 
SUBTASK OF 
CONTROL TASK 



Z (task T2) 
SUBTASK OF Y 



Figure 14.2. The hierarchy of tasks 
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CONTROL TASK 





All code that could affect other 
task's housekeeping is handled in 
the control task: 

Attaching tasks 

Detaching tasks 

PRIORITY and 

COMPLETION pseudovariables 

All access to EVENT variables 














SUBTASKS OF 


CONTROL TASK 





PL/I MAJOR TASK 



PL/1 SUBTASKS 



Any operation that could affect 
another task's housekeeping is 
handled by a call to the central 
task. 



Any operation that could affect 
another task's housekeeping is 
handled by a call to the central 
task. 



Figure li».3. The functions of the control task 
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PL/I MAJOR TASK 
TASKING APPENDAGE 



POST ECB 



PARAMETERS 

Used by code executed in 

control task 



WAIT ECB 



CONTROL TASKS ECB LIST 



ECB list element for 
major task 



ECB list element for 
subtask 



Control tasks waits on 
these ECBs which are posted 
with a code indicating the 
service the subtask requires 



Parameters further define 
the service if necessary 



PL/I task waits on this ECB. 
It is set complete in the 
control task when the 
required service is completed 



Control task waits on this list until 
required to perform a service 



PL/I SUBTASK 
TASKING APPENDAGE 



POST ECB 



PARAMETERS 

Used by code executed in 

control task 



WAIT ECB 



Figure 14. U. The post and wait ECBs 
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Modules in the tasking library 



Control Link-edit Function 
Name* Name* 



IBMTPIR IBMBPIRA 

IBMTPGR IBMBGGRA 

IBMTPGO IBMBPGOA 

IBMTTOC IBMBTOCA 

IBMTTPR IBMBTPRA 



program 

initialization and 
task housekeeping 

Storage management 

Abnormal GOTO 

COMPLETION 
pseudovariable 

PRIORITY 
pseudovariable 



IBMTJWT IBMBJWTA WAIT Statement 



Multitasking Modules in the Transient 
library 



IBMTPJR IBMTPJRA 



IBMTPJI IBMTPJIA 



Program initial- 
ization and task 
housekeeping 

Program initial- 
ization 



♦ control name is the name that 
uniquely defines the module. 

Link-edit name is the name by which a 
module is known to the linkage editor. 
Multitasking and non-multitasking 
modules that handle similar functions 
have the same link-edit name. 



information than is available in the DSA 
chain is required. In addition to the DSA 
chain, tasks with the same attaching task 
are chained together, and the most recently 
attached subtask is chained to its parent 
task. The chains between tasks with the 
same attaching task are known as sister 
task chains. The sister task chains and 
the chain to the most recently attached 
subtask are all held within the tasking 
appendage. The chaining arrangement, shown 
in figure 1U.7, allows quick access to all 
related tasks. 

The sister task chain goes in both 
directions. Each task is chained to the 
task attached immediately before it (elder 
sister) and the task attached immediately 
after it (younger sister) . The most 
recently attached task has no younger 
sister. Its younger sister chain points 
instead to the attaching task. However, 
instead of pointing at the head of the 
tasking appendage, it points at offset X'8' 
within the tasking appendage. The effect 
of this is that an attempt to continue to 
follow the younger sister chain results, 
beyond the attaching task, in access not to 
the younger sister pointer but to a field 
offset from it by X'8*. This field, which 
is always set to zero in all tasks, is 
known as the stopper. field. Access to it 
indicates that the attaching task has been 
reached. 

When a task is terminated, all its 
subtasks must be terminated. To simplify 
finding these tasks, a flag is set in the 
DSA of the block in which a task is 
attached. The flag remains set while any 
active tasks are attached. 



Figure .14.5. Modules in the 

multitasking library 



The Multitasking Library 



function correctly,, certain items, such as 
on-cells and dynamic ONCBs, are copied from 
the attaching task*s DSA to the dummy DSA 
of the attached task at the time of 
attachment. 

If procedures executed as separate tasks 
are internal to one another, a static 
backchain is established through the DSAs. 
This backchain passes from the attached 
task's procedure DSA to the DSA of the 
procedure in which the task was attached, 
and is the same as for non-multitasking 
programs. This chaining allows all 
internal procedures to access variables 
declared in outer blocks without requiring 
special provision for multitasking. 
(Special action is,, however,, necessary when 
handling the CHECK condition.) 

To maintain the PL/I hierarchy, more 



Module IBMTPIR loads IBMTPJR to perform 
most multitasking functions. IBMTPJR 
carries out the majority of functions that 
are executed in the control task. IBMTPJR 
issues a LOAD macro instruction to pass 
control to IBMTPJI to perform parameter 
translation, and to initialize the control 
task and the storage for the major task. 
IBMTPJR then attaches the major task. 
IBMTPJR also contains the instructions to 
handle the major functions which have to be 
carried out within the control task., Each 
of these functions is handled by a 
particular subroutine within IBMTPJR. A 
simplified flowchart of IBMTPJR is shown in 
figure 14.8. 

The program initialization module 
IBMTPJR has a register save area, but is 
unlike other PL/I library routines in not 
having a DSA. IBMTPIR acquires workspace. 
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MAJOR TASK TCA 



^X 



i — 



Program 
Management Area 




SUBTASK1 TCA 




SUBTASK2TCA 


MAJOR TASK 
DUMMY DSA 




Program 
Management Area 




Program 
Management Area 


MAIN PROCDSA 


DUMMY DSA 


DUMMY DSA 


1 


[ 




BEGIN BLOCK 
DSA 


Procedure DSA 


Procedure DSA 











PL/I procedures involved 



Main procedure (major task) 
Begin block 
Procedure for subtask! 
Procedure for subtask2 



Note: To allow for inheritance of on-units, information 
held in the DSA of the attaching task is copied into the 
dummy DSA of the attached task. 



Key 



Static backchain 
Dynamic backchain 



Figure 14.6. Backchains in multitasking 
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Tasking appendage 
major task 



younger sister (O) 
elder sister (O) 



stopper (0) 
subtask chain 



Major task 
Task 1 



Task 2 



■ Tasking appendage * . 
I, task 1 




/Tasking appendage * . 
1 task 2 



Tasking appendage x 
task 3 



younger sister 
elder sister 



stopper (0) 
subtask chain (O) 



/ 






younger sister —f 
• elder sister 



stopper (0) 
subtask chain (O) 






/ 



younger sister 
elder sister 



stopper (0) 
subtask chain 



N 



/ 



\ 



Subtask chain points to most 
recently attached subtask. 
Younger sister chain 
(i.e. tasks with the same 
attaching tasks that were 
attached later) 

Elder sister chain 
(e.i. tasks with the same 
attaching task that were 
attached earlier) 



Tasking appendage 
task 3a 



younger sister 
elder sister (O) 



stopper (0) 
subtask chain (O) 



/ 



Note: Because tasks are chained in both directions, all relationships be quickly found. 

Following the 'younger sister chain' leads to the attaching task. When the attaching task is reached, the offset that should be the 
offset to the younger sister is to the stopper. Thus it is known that the attaching task has been reached. 

Figure 14.7. The chaining of tasks through their tasking appendages 



262 



Subroutines executed 
in control task 



/^ 



"X 



Main Program Flow (IBMTPIR) 
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Subroutines entered viaTCA orTCA appendage from PL/ltasks 
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ATTACH 
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Create a subtask 








Initialize major 
task 












COMPLETION 








' 


Set completion of 
event variable 






-* \ 








Initialization 
common to 
all tasks 






PRIORITY 




Set priority of 
task variable 










, 




* r 


I 


Post wait-ECB 
complete 




i 


EVENT ASSIGN 




Set completion 
and priority of 
event variable 








t 




i 


i 


Wait on 
ECB list 


COMPLETE 
EVENT 




Used by 
wait module 








i 


i 


1 


DECHAIN EVTAB 




1 


Used by wait 
module 




1 






WAIT STATE 










1 




Execute code 
indicated until 
free control call 
is reached 


i 


1 


Execute in 
control task 




i 


1 
1 

1 








Control resumed 
here 










END OF BLOCK 




Detach tasks 
if necessary 




^ 




t 


1 


Search ECB list 
to determine which 
service is required 
and set ECB 
incomplete 




i 


END OF TASK 




Terminate task 




^y^^ Major — >^^ 

^^^ taqk ^■^ 


No 




* 






^\1^^ 


'r 








Branch to 

appropriate 

subroutine 


STOP 




1 


^Yes 




Execute STOP 
statements. 


r END ^ 




















' 


r 



c 



ENTRY 



> 



L_ 



Call task 
End task 
Return 
Get control 



Carry out 
checking 
set up 
parameters 



Post post ECB 
with correct 
completion 
code 



Wait on 
Wait ECB 



WAIT STATE 



Return to caller 



c 



ENTRY 



> 



Enqueue 
SYSPRINT 



Check whether 

SYSPRINT 

enqueued 



Enqueue 
SYSPRINT 
if necessary 



Return to caller 



Dequeue 
SYSPRINT 




Dequeue 
SYSPRINT 



Return 



Free control — executed in control task 



c 



ENTRY 



> 



Restore DSA 
of Get Control 
routine 



Figure 14.8. A simplified flowchart of IBMTPIR 
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contiguous with the standard register save 
area, to hold: the addresses of the ECB 
lists; the address of the area where the 
next ECB- list element will be placed; the 
task-end ECB (used when detaching a task - 
see below), the diagnostic file block, and 
the dump block. These last two blocks are 
held in the control task workspace because 
they must serve for all PL/I tasks. 

Supporting IBMTPJR are two routines that 
are link- edited only when necessary: 
IBMTTOC is link-edited only if the 
COMPLETION pseudovariable is used; IBMTPRA 
is link-edited only if the PRIORITY 
pseudovariable is used. 

Also included in the multitasking 
library are a number of routines that 
handle action which requires different 
machine instructions for a multitasking 
program. Among these routines are storage 
management and error handling routines. 

All the routines in the multitasking 
library are shown in figure 14.5 and 
described in OS, PL/I Resident Libraryi., 
Pro gram Logic . "" *" 



list, discover which ECB has been posted, 
and then to carry out the action specified 
in the code posted in this ECB. The action 
is carried out by calling a subroutine of 
IBMTPJR. This subroutine may perform the 
function required, execute a sequence of 
requested instructions, or call further 
library routines to handle the requested 
function. 

Whenever a new subtask is attached, a 
further POST ECB is added to the ECB list 
of the control task. 

Whenever PL/I tasks require a service 
that is handled in the control task, a call 
is made to a library entry point. The 
majority of calls are to subroutines of 
IBMTPJR, which are addressed via the TCA or 
the TCA appendage. However, the PRIORITY 
and COMPLETION pseudovariable routines are 
separate library modules. This saves space 
in programs where the pseudovariables are 
not used. 



Attaching a Task 



How the Control Task Operates 



The control task is created by the system 
when the PL/I program is initialized. The 
instructions first executed within the 
control task are in the program 
initialization routine IBMTPIR. This 
routine is entered because its address is 
specified in the control section PLISTART 
(see chaptet 5), 

IBMTPJR obtains a standard save area, and 
then loads and branches to IBMTPJR which 
performs the remainder of the 
initializ at ion . 



A CALL statement with one of the 
multitasking options is compiled as a call 
to an entry point in IBMTPJR. This entry 
point is addressed via a module list whose 
address is held in the TCA. The entry point 
is passed the address of the procedure that 
is to be executed as the attached task, and 
any parameters that are to be passed to 
that procedure. 

The routine in IBMTPJR posts the POST 
ECB for the attaching task with a 
completion code of 24, indicating that a 
new task is to be attached. It then issues 
a WAIT macro instruction on its own WAIT 
ECB, and the attaching task goes into the 
wait state. 



IBMTPIR sets up the environment for the 
major task, which it then attaches with an 
ATTACH macro instruction, after further 
initialization, control is given to the 
address held in PLIMAIN 

IBMTPJR then builds an ECB list which 
consists of the WAIT ECBs for the PL/I task 
that has been attached plus the task-end 
ECB. A wait is then issued on this ECB 
list, and the control task will remain in 
the wait state until the major task 
requires a service that must be handled in 
the control task. 

When control returns to the control 
task, execution recommences in IBMTPJR 
immediately after the point at which the 
WAIT macro instruction was issued. The 
action at this point is to search the ECB 



control passes to the control task. The 
first action of the code within the control 
task is to scan the ECB list to see which 
task is requesting a service, and which 
service is being requested. According to 
the completion code in the ECB, one of the 
subroutines in IBMTPJR is entered. For 
attaching a task, the attach-task 
subroutine is entered. The minimum storage 
the subroutine attempts to acquire is a new 
program management area. Depending on the 
options in the ISASIZE parameter, it may 
also attempt to acquire storage for DSAs 
and other dynamic requirements. 

The new program management area is set 
up within the storage acquired, and the new 
TCA is placed at the head of the chain of 
daughter tasks that is held in the 
attaching task's TCA. 
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The new TCA is then associated with a 
task variable and an event variable. If 
these were specified in the CALL statement, 
they are used, otherwise, dummy event and 
task variables are set up by IBMTPJR. 
These dummy variables are held in the 
working storage of the new block. The 
event and task variables are then chained 
to and from the TCA. A bit is set in the 
DSA of the block that was being executed 
when the task was attached. 

The PRV of the attaching task is then 
copied into the attached task. This 
ensures that addressing information for 
files and controlled variables cannot be 
altered by the attaching task, similarly, 
on-unit establishment information is copied 
from the attaching task's current DSA into 
the dummy DSA of the attached task. This 
ensures that the subtask acts according to 
the situation prevailing at the time when 
the call was made. 

The attaching routine finally sets the 
POST ECB of the new task incomplete, adds 
this new POST ECB to the control task's ECB 
list, completes the ECB on which the 
requesting task is waiting, and issues a 
WAIT macro instruction on the control 
task's ECB list. 



Detaching a Task 



Tasks are normally detached when they reach 
any EXIT statement, or an END or RETURN 
statement in the procedure that was 
attached as a task. In such circumstances, 
control returns in the normal manner to 
IBMTPIR, whose registers have been stored 
in the dummy DSA of the task. IBMTPIR is 
then in a position to pass control to the 
control task, so that the requesting task 
can be terminated. After housekeeping 
operations, the control task sets the 
priority of the task to be detached as high 
as possible, completes the WAIT ECB of the 
task, and then waits on the task-end ECB. 
When the task to be terminated resumes 
control, it posts the task-end ECB 
complete, and terminates itself by 
returning to the control program. 

The process described above is used 
because it is simpler than handling the 
ABEND that would otherwise result when one 
task is detatched from another. 



Abnormal Termination of a Task 



The newly attached task and the original 
requesting task are now both ready to 
receive control from the control program. 
The control task is in a wait state, ready 
to service any further requests from PL/I 
tasks. 



Failure of CALL. ..TASK Statements 



When a block is terminated, any tasks 
attached during the execution of the block 
are also terminated. For this reason, 
epilogue code of blocks in which tasks iray 
be attached contains a call to a subroutine 
of IBMTPIR. This subroutine passes control 
to the control task, from which the purge 
task subroutine is called. This routine 
examines the DSA of the block being freed, 
to see whether any active subtasks remain; 
if any do remain, they are terminated. 

Active subtasks are accessed via the 
chain of daughter tasks from the TCA of the 
task in which the block is being 
terminated. 



A number of situations can cause a 
CALL.. TASK Statement to fail. These 
situations are: 

1. Too many tasks are already active 

2. There is insufficient storage for the 
new task 



Abnormal termination of a task involves 
ensuring that any WAIT statements being 
executed by the task are properly 
terminated, event variables are completed, 
task variables are set inactive, and ECB 
elements are removed. Event I/O operations 
started in the tasks are completed. 



3. The task variable is already active 

H. The event variable is already active 

In any of these situations,, the calling 
task is posted with a non-zero postcode. 
When this postcode is detected, the task 
generates the correct error code, and calls 
the error handler. 



The Get-Control and Free-Control Routines 



In order to increase the scope of jobs that 
can be handled within the control task, the 
program initialization routine includes a 
facility whereby a request can be made for 
any defined sequence of instructions to be 
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8. 



Chains and Pointers used during execution of 
WAIT statement 



ISA for task 1 



ISA for task 2 



1. EVTAB chain. Headed by the event 
variable. Connects all WAIT state- 
ments that use the same event 
variable, and enables the information 
that events are complete to be passed 
to all tasks. 

2. WIT chain. Headed in the TCA. 
Connects all WAIT statements being 
executed in one task, and enables 
the EVTABs of these waits to be 
removed from the EVTAB chain 
when a task is terminated during a 
WAIT statement. 

3. Event variable pointer. Held in 
EVTAB. Used to access event 
variables and search EVTAB chain. 

4. ECBLIST element pointer. Held in 
EVTAB. Used to find associated 
ECB if event is an I/O event. 

5. TCA appendage pointer. Held in 
EVTAB. Used during task 
termination. 

6. EVTAB pointers. Held in WIT. Used 
to indicate number of EVTABs when 
dechaining during abnornal 
termination caused by GOTO out of 
block. 

7. ECB pointer. Held in event variable. 
Used, for I/O events only, to 
identify associated event. 



J7 



Program management area 



r- 



t 



LIFO storage 






DSA for WAIT module 



WIT 



EVTABs 



ECB-llst 
Addresses of associated ECBs 



Major free area 



•^ 
1 



Program management area 



^in 



© 



-<i) 



9. 



JCA appendage pointer. Held in 
event variable. Used, for I/O events 
only, during building of EVTABs 
to test whether I/O is active in the 
task. 

ECB pointers. Held in ECB list. 
Used by supervisor to test whether 
events are complete. 



lOCB 



l@^ 



LIFO storage 



I 



DSA for WAIT module 



WIT 



EVTABs 



-<3> 



ECB-list 
Addresses of associated ECBs 



DSA for on-unit 



DSA for WAIT module 
called in on-unit 



WIT 



EVTABs 



ECB-list 



Major free area 



® 



® 



O 



® 



Pointer to event variable 



ECB 



EVENT VARIABLE 



Q) 



<!> 



PRIORITY and COMPLETION flags 



Pointer to ECB in lOCB If I/O event 



— dH 



Start of chain of EVTABs 



Address of TCA appendage of task 
requiring 1/0(1/0 event only) 



Figure m .9 . Chains and pointers used in implementing the WAIT statement 
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executed within the control task. This 
facility is used by a number of library 
routines when accessing event variables, or 
carrying out other actions that have to be 
executed within the control task. It is 
not used by compiled code. 

The instructions to be executed within 
the control task are delimited by calls to 
two library subroutines, whose addresses 
are held in the TCA. These routines are 
the get~control and f ree^cpntrol routines. 
Both are subroutines of IBMTPIR. 

When the get-control routine is called 
within a PL/I task, it saves the caller's 
registers, posts its POST ECB, and issues a 
wait on the requesting task's ECB. 

When the control task gains control, it 
restores the registers saved by the get- 
control routine, and branches to the 
address in register 14. The address will 
be the instruction after the call to the 
get-control routine, because the routine 
was called in the standard manner, that is, 
a BALE instruction on registers lU and 15. 

Execution of the instructions then 
continues in the control task until a call 
to the free-control routine is met. This 
routine stores the current registers in the 
DSA of the block that originally called the 
get-control routine. The free-control 
routine now posts the WAIT ECB of the 
requesting task, and resets the control 
task waiting on its ECB list. 

During execution of the free-control 
routine, the routine modifies the value in 
the register 14 save area in the DSA of the 
block that originally called the get- 
control routine. When control returns to 
the original requesting task, it returns to 
the point in the get- control routine 
immediately following the point where the 
WAIT was issued. The get- control routine 
restores the register values, and branches 
to the new address in register 14. 

The required instructions have now been 
executed within the control task, and 
execution can continue in the original 
task. The processes involved in the get- 
control and free-control routines can be 
followed in the flowchart of IBMTPIR in 
figure 14.8. 

Altering COMPLETION and PRIORITY 
Values 



TO prevent two PL/I tasks attempting to 
alter the completion and priority values of 
tasks or events at the same time, 
alteration of these values is always done 
by code in the control task. 



When such access is required, compiled 
code in the requesting task branches to a 
library subroutine that posts the control 
task with a completion code in the POST 
ECB, and issues a wait in the requesting 
task. When the control task receives 
control, it inspects the completion code, 
and calls a subroutine in IBMTPIR. For the 
PRIORITY pseudovariable, the subroutine in 
IBMTPIR calls a subroutine in IBMTTPR to 
handle the actual alteration. This is to 
save space in programs where the PRIORITY 
pseudovariable is not used. 

The subroutine accesses and alters the 
values as requested. Where necessary, a 
CHAP macro instruction is issued to alter 
the priority of a task. 



Executing the WAIT Statement 



The WAIT statement can be used in both 
multitasking and non-multitasking programs. 
A description of WAIT in the non- 
multitasking situation is given in chapter 
11. 

At the PL/I level, each WAIT stateirent 
is associated with one or more events, and 
each event is associated with an event 
variable. When the specified number of 
these event variables is set "complete," 
the wait is terminated. 

PL/I event variables are not accessed by 
system wait macro instructions; they 
contain a pointer to the event's ECB. This 
ECB will have been nominated in the WAIT 
macro instruction issued to the system, and 
will be set complete when the associated 
event is complete. When the event is 
complete, the PL/I program can inspect the 
ECB, and complete the event variable. 

The PL/I event variable cannot be used 
to indicate to all WAIT statements 
nominating the associated event that the 
event is complete. This is because an 
event variable may be associated with a 
further event immediately after completion 
of the event with which it was formerly 
associated. If more than one task is 
waiting, this may be before all the WAIT 
statements nominating the event are 
satisfied. See figure 14.10. 

To overcome this problem, a control 
block known as an EVTAB is used. An EVTAB 
is generated for every WAIT statement. For 
every event nominated in the statement, an 
EVTAB element is produced, containing the 
ECB for the event and a pointer to other 
EVTAB elements associated with the event. 
Thus, when an event is completed in one 
task, the chain from the event variable is 
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scanned and any ECBs associated with the 
event are set complete. 

A further control block is used in the 
implementation of the WAIT statement. This 
is the wait information table (WIT) . A WIT 
contains a record of any WAIT statements 
that are being executed in a particular 
task. This information is used when a task 
is being terminated, because any active 
events must be removed from the chain that 
associates event variables with EVTABs. 
Were this not done, the chaining of EVTABs 
would be destroyed because the EVTABs in 
the terminated task would be lost. 

The chaining of the control blocks 
described above is shown in figure 14.9. 



The Wait Module IBMTJWT 



The WAIT statement is executed by means of 
a call to the wait module, IBMTJWT, The 
module is passed a list of event variables 
and,, optionally,, a value indicating how 
many of the events must be completed before 
the wait is satisfied. If no value is 
specified, all events must be completed. 

The wait module may be passed various 
types of event variable: 



1. Active event variables, 
associated with: 



These are 



a. I/O or display events that were 
initiated in the current task. 

b. I/O or display events that were 
initiated in another task. 

c. Events associated with tasks. 



completed, and the associated ECBs in other 
tasks set complete, the error handler is 
called to terminate the current task. 

If the WAIT statement can be satisfied 
by completable event(s), the incompletable 
event is ignored. 

If any of the events are I/O or display 
events initiated in the current task, an 
ECB will already have been created for 
these events when the statement with the 
EVENT option was executed. This ECB must 
be accessed and waited on. Access is made 
through the event variable. 

Note that for I/O events, a CHECK macro 
instruction is issued by the I/O 
transmitter. If all events are I/O events 
initiated in the current task, and all of 
them have to be completed, it is possible 
to use the CHECK macro instruction to 
satisfy the WAIT statement. The wait module 
passes the events one at a time to IBMBRIO. 
Return is made when the event is complete. 
The wait module then searches the EVTAB 
chain, setting any associated ECBs 
complete. It then passes the next event to 
IBMBRIO, continuing the process until all 
events are complete. If all events need 
not be completed, this method cannot be 
used, because one of the events nominated 
might prove incompletable and, conseqently, 
the task would be terminated. 

If the events are not I/O or display 
events initiated in the current task, the 
wait module builds an EVTAB element for the 
event, and associates it with the event 
variable. If only one event is involved, 
the wait module then issues a WAIT macro on 
the ECB; if more than one event is 
involved, the wait module places the 
address of the ECB in an ECB list on which 
a WAIT macro instruction will be issued. 



2. Inactive event variables. These are 
associated with events that must be 
completed by use of the COMPLETION 
pseudovariable. 

3. Incompletable event variables. These 
are associated with events that have 
caused entry to an on-unit because an 
I/O condition has been raised in the 
current task,, and which cannot be 
completed because the on-unit also 
specifies a wait on the event that is 
already being waited on. 

If any of the events are incompletable, 
IBMTJWT checks to see whether the WAIT 
statement can be satisfied by completable 
events. If the WAIT statement cannot be 
satisfied, an attempt is made to complete 
all I/O and display events initiated in the 
current task, as other tasks may be waiting 
on these events. When these events are 



If the wait module issues a WAIT macro 
instruction on an ECB list, control will 
return to the module when one or more of 
the ECBs has been completed. 

The wait module scans the EVTAB elements 
and discovers which of the events has been 
completed. If the event is an I/O event in 
the current task, it will be necessary to 
complete the event variable and scan the 
EVTAB chain, completing ECBs in any tasks 
that are waiting on the event that has been 
completed. The ECBs are completed by 
calling a subroutine of IBMTPIR, which 
executes the necessary instructions in the 
control task. The subroutine completes the 
ECBs by means of a POST macro instruction. 

If the wait is to be made on events that 
can only be completed in other tasks, the 
wait module issues a WAIT macro instruction 
specifying that all the events in the ECB 
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TASK 1 



TASK 2 



WAIT (El) ; 



WAIT (El); 



READ FILE (A) 
INTO (B) 
EVENT (El) ; 



Task 1 reuses the event variable El. If 
task 1 acquires control before task 2 on 
completion of the original event with 
which El is associated,, then the event 
variable on which task 2 is waiting will 
be associated with an event other than 
that originally intended. A mechanism 
to supplement the event variable is 
therefore needed: this mechanism is 
known as the EVTAB chain. In the above 
example, the EVTAB chain would allow 
task 2 to determine that the original 
event was complete. 



Figure 14.10. 



Reusing event variables, 
and the need for the 
EVTAB chain 



list must be completed. 

When all completed ECBs have been 
handled, the ECB list and the EVTAB 
elements are rebuilt for all events that 
are not complete. A further WAIT macro 
instruction is issued on the ECB list, and 
the process is continued until the 
necessary number of events have been 
completed. 



If the number of events needed to 
satisfy the WAIT statement are complete, 
but further events remain incomplete, it is 
necessary to dechain EVTABs from the chains 
associated with the incomplete events. 
This is done by a call to a subroutine in 
IBMTPIR, v^ich executes instructions in the 
control task to r«nove unneeded EVTAB 
elements from the EVTAB chain. 



If the WAIT statement specifies only 
active events, no further action can be 
taken until the events are complete. 
Accordingly, the wait module issues a WAIT 
macro instruction specifying that all 
events have to be completed. Thus control 
will not return to the task until the wait 
is satisfied. 



Enqueuing and Dequeuing on SYSPRINT 



In order to protect error messages from 
interruption by other output to SYSPRINT, 
or from error messages in different tasks, 
the error message modules and all calls to 
SYSPRINT are enqueued and dequeued by means 
of a call to a subroutine in IBMTPIR, which 
issues the ENQ and DEQ macro instructions. 
A call is made immediately before and 
immediately after the output. 

Similar action is taken on EXCLUSIVE 
files, for which the ENQ and DEQ macro 
instructions are issued by the library 
module IBMBPQD. 
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Appendix A: Control Blocks 



This appendix provides information on the 
format of the control blocks that may be 
used during the execution of a program 
compiled by the OS PL/I Optimizing 
Compiler. Brief details of the function of 
each control block, together with when it 
is generated and where it can be located, 
are also given. 



Except where explicitly stated all 
offsets from the start of a block are byte 
offsets and are given in hexadecimal 
notation. 
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Area Locator/Descriptor 



Function 

Holds the address and length of the area 
variable for passing to other routines or 
for execution time reference if the area 
has an adjustable length. 



When Generated 



From an offset from register 3 known to 
compiled code 



0| 

I 

41 



A (AREA VARIABLE) 
LENGTH 



A (Area Variable) is the address of the arec 
variable control block. 

Length is the total length including both 
the control block and the area variable. 



As far as possible during compilation, 
necessary completed during execution. 



If 



Where Held 



Static internal control section. 



How Addressed 



AREA DESCRIPTOR 



The area descriptor is the second word of 
the area locator/descriptor. It is used in 
structure descriptors, when areas appear in 
structures, and in the controlled variable 
'description' field when an area is 
controlled. 
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Area Variable Control Block 



Function 



Used to control storage allocation within 
the area variable. 



When Generated 



E£gg-§lgggS^s ; If there are free elements 
in the area~variable, they are headed by 
two words. The first word gives the length 
of the element, the second word gives the 
offset to the next smaller free element. 
If there is no smaller free element, the 
second word is set to zero. 

Flag X'O* Area variable does not contain 
free elements. 
X'l* Area variable does contain free 
elements. 



When the area variable is initialized. 
This depends on the storage class of the 
area. 



Where Held 



At the head of the area variable. 




H 
8 
C 
10 



FLAG 



UNUSED 



OFFSET OF END OF EXTENT (OEE) 
OFFSET OF LARGEST FREE ELEMENT (LFE) 



END OF CHAIN OF FREE ELEMENTS 



Area variable 
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Aggregate Descriptor Descriptor 



Base Element 



Function 



Contains information needed to map a 
structure or an array of structures during 
execution. Used for structures that 
contain adjustable extents or the REFER 
option. See chapter U. 



12 

r T 

0|1 |Fi| ALIGNMENT | LENGTH | 

, , 

2 1 Level IF2IF3I DIM | 

L J 



When Generated 



As far as possible during compilation. 
Adjustable values are filled in during 
execution. 



Where Held 



Static internal control section. 



How Addressed 

From an offset from register 3 known to 
compiled code 



General Format 



An aggregate descriptor descriptor consists 
of a series of fullword fields one for each 
structure element and one for each base 
element in the structure. 



Structure Element 



12 

r 1 

0|0 I Fi, I Offset to entry for containing | 
i I I block i 

, , 

2 1 Level iFaJFal DIM j 



where. 



Fx = *0*B Not last element in structure 
= 'I'D Last element in structure 

Fa = 'O'B Not an AREA 
= '1*6 An AREA 

F3 = 'O'B Not a BIT string 

= 'I'B BIT string 

OFFSET = The offset within the 
aggregate descriptor 
descriptor to the entry for 
the containing structure. 
The offset is held in 
multiples of four bytes. 

LEVEL = Logical level of identifier 
in structure 

DIM = Real dimensionality of 
identifier 

ALIGNMENT = Alignment stringency 

Value (dec.) Meaning 






bit 


7 


byte 


15 


half-word 


31 


word 


63 


double-word 



LENGTH 



= Length (in bytes) of data 

LENGTH = for strings and 

AREAS, whose length 
is held in 
descriptors 
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Ag^l^G^clte Locator static internal control section. 

Function How Addressed 

From an offset from register 3 known to 
Used to pass the address of an array or compiled code 
structure and its associated descriptor to 
a called routine. Also to associate the 

aggregate with its descriptor during 4 

execution . i- 1 

0| Address of data aggregate | 
, 1 

4 1 Address of descriptor | 

L -J 

When_Generated 
During compilation. 



Where Held 
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Array Descriptor 



Function 



Contains information about the extent of an 
array. For arrays of area variables or 
strings, an area or string descriptor is 
attached to the array descriptor. 

The array descriptor is used to pass 
information about an array to called 
routines, or to hold information about an 
array with adjustable extents. 



When Generated 



4 
8 
C 
10 





RVO 


(AO-VO) 










Mult 


iplier 








High 


bound 


1 


Low 


bound 






Multiplier 


2 






High 


bound 2 


1 


Low 


bound 


2 



etc. 

Note;. Two full words containing 
multiplier and high and low bound are 
included for each array dimension 



hs far as possible during compilation. If 
the array has adjustable extents, it is 
completed during execution when the values 
are known. 

Arrays of structures make use of 
structure descriptors to hold similar 
information. 



Where Held 



Static internal control section. 



How Addressed 



From an offset from register 3 known to 
compiler code 



Arra ys of strings.gr Areas 



For arrays of strings or areas, the 
descriptors are completed by string or area 
descriptors concatenated to the array 
descriptor. String and area descriptors are 
the second word of string and area 
descriptor/ locator pairs. 

For bit string arrays,, the bit offset 
from the byte address is held in the string 
descriptor. 



General Format 

The first word in the array descriptor is 
the RVO (relative virtual origin). This is 
followed by two words for each dimension of 
the array, containing the multiplier and 
high and low bound for each dimension. 



RVO = Relative virtual origin, the 
distance between the virtual 
origin (VO) and the actual origin 
(AO) . Virtual origin is the point 
at which the element in the array 
whose subscripts are all zeros is, 
or would be, held. Actual origin 
is the start of the first element 
in the array. 



RVO is held as a bit value for 
arrays of unaligned bit strings, 
but otherwise as a byte value. 
Bit offsets are given in the 
string descriptor. Actual origin 
and virtual origin are also held 
as byte values. 

High bound: 

The highest subscript in any 
dimension. 

Low bound: 

The lowest subscript in any 
dimension. 

Multiplier: 

The multiplier is the offset 
between any two elements marked by 
the change of subscript number in 
any dimension. 

For example for the array DATA(10,10), 
the multiplier for the first dimension is 
the offset between DATA (1,1) and DATA (2,1) 
etc. The multiplier for the second 
dimension is the offset between DATA (1,1) 
and DATA(1,2). The offset is measured from 
the start of the one element to the start 
of the next. 

Multipliers are byte values except for 
bit string arrays, in which case they are 
bit values. 
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Controlled Variable Block 



WORD 1 
WORD 2 
WORD 3 
WORD H 
WORD 5 




4 
8 
C 
10 





ti 


PRVOFF 


LENGTH 


Chain back to previous allocation 


Task Invocation Count 



DESCRIPTION 
Field used for descriptor or 
locator/descriptor in certain 
circumstances, (see below) 




Address held in pseudo register 
< 



Function 



To hold information about the controlled 
variable. 



TASK INVOCATION COUNT: A method of 

identifying which task the 
controlled variable is 
attached to. A controlled 
variable cannot be freed 
within a task unless the task 
invocation count of the 
variable is the same as that 
in the TCA. 



♦DESCRIPTION 



When Generated 



When the variable is allocated. 



Where Held 



At the head of the controlled variable. 



Hgw_Addre§sed 

From an offset in the PRV. (The PRV 
address is held out offset X'U* in the 
TCA.) 

PRVOFF: Offset within pseudo-register 
vector associated with the 
controlled variable. 

LENGTH: Length of the total allocation 
including the 4 words of the 
heading. 

CHAIN BACK: Address of word 5 of previous 
allocation, set to address of 
dummy FCB if first allocation. 



If the item is one that 
requires a descriptor/locator 
or a locator,, this is placed 
at the head of the data. If 
the item is a structure or 
array and the extents are 
unknown at compile time, the 
descriptor will also be placed 
before the data. 

Thus for: 

STRINGS and AREAS, the 
controlled variable is headed 
by a locator/descriptor 

STRUCTURES and ARRAYS, the 
controlled variable is headed 
by a locator 

STRUCTURES and ARRAYS with 
ADJUSTABLE EXTENTS, the 
controlled variable is headed 
by a locator followed by a 
descrip tor 

ALL OTHER DATA, the 
description field is not used 
and the data itself starts at 
offset X'lO' (16) 
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Data Element Descriptor (DED) 



Function 



Used to pass description of data elements 
to library conversion and stream I/O 
routines. 



When Generated 



During compilation. 



Where Held 



Static internal control section. 



How Add re ssed 

From an offset from register 3 known to 
compiled code. 



Format of DEDs 



All DEDs are headed by two bytes that 
indicate the data type. These two bytes 
are followed by as many bytes as are 
required to complete the description of the 
data. 

For arithmetic items, DEDs are completed 
by such items as scale and precision. For 
pictured items,, a representation of the 
picture is included in internal form. 



Hex Value 


Data Type 


00 


FIXED BINARY 


04 


FIXED DECIMAL 


08 


FLOAT 


OC 


Free decimal (an 




internal form) 


10 


FIXED PICTURE BINARY 


in 


FIXED PICTURE DECIMAL 


18 


FLOAT PICTURE BINARY 


IC 


FLOAT PICTURE DECIMAL 


20 


non- VARYING CHARACTER 


2U 


non-VARYING BIT 


28 


VARYING CHARACTER 


2C 


VARYING BIT 


30 


CHARACTER PICTURE 


UO 


BINARY constant 


^^^ 


DECIMAL constant 


48 


BIT constant 


50 


F/E Format 


5U 


P Format (arithmetic) 


58 


A/B/P Format (character) 


5C 


C Format 


60 


X Format 


64 


COL Format 


68 


SKIP Format 


6C 


LINE Format 


70 


PAGE Format 


80 


LABEL 


84 


ENTRY 


88 


AREA 


8C 


TASK 


90 


OFFSET 


94 


POINTER 


98 


FILE 


9C 


EVENT 


Flag Byte 


_2 



Bits OSl = 'OO'B A- format item 
•01*B B-format item 
•lO'B character picture format 
item 



Bit 2 = '0*B fixed constant 
•1»B float constant 



General Format 



Bit 3 = 'O'B not extended float 
'I'B extended float 



12 

J. . . -. . 

1 Flag byte 1 IFlag byte 2 | 

I I I 

I Defines data | Completes | Further bytes 
I type I definition |as required 
I I if necessary! 

Flag By te 1 (also known as Code Byte and 
Lookup Byte) 



Bit 4 = 'O'B F-format/fixed picture 

•I'B E~format/float picture 

Bit 5 = "O'B declared binary 

*1*B declared decimal 

If bits 4 and 5 = 'll'B then DED is for 
character 

Bit 6 = 'O'B short precision 

•I'B long precision 
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Bit 7 = 



*0'B real or length specified (A 
or B format) unaligned bit 
string 

*1'B complex (also set if E, F, or 
P in C- format) or no length 
specified (A or B format) or 
aligned bit string 



All bits for which neither value is 
defined are set to "O'E 



Li = length of field with insertion 
characters 

La = length of field without insertion 
characters 



DED for PICTURE DECIMAL Arithmetic Data 



DED for STRING data 



J. ^ 

I Flag byte 1 |Flag byte 2| 
L -, J 



DED for FLOAT Data 



0| Flag I Flag | Precision | Scale 
I Byte 1 I Byte 2 | jFactor+128 



41 Length of | Length of | Flag | Flag 
I Picture jData |Byte 3 | Byte U 



Picture in internal code 



Flag byte 1 = Hex 14 or IC 

Flag Byte 3 (describes the mantissa 
subfield) 



1 2 3 

^ . ^ 

1 Flag byte 1 |Flag byte 2 | precision) 
L J 



DED for FIXED Data 



1 2 3 4 

r — ■ "I 

1 Flag byte 1 | Flag byte 2 1 precision | scale) 

I I I 1/128 ) 

L , —J 



DED for PICTURE STRING Data 



0) Flag ) Flag ) 
j Byte 1 i Byte 2 ) 



{Picture in internal 
jforro 



Flag byte 1 = Hex 30 

The internal code for string pictures is 
as follows: 



Code Picture ( he x ) 

A 00 

9 04 

X IC 



Bit = 



Bit 1 = 'I'B 
= 'O'B 

Bit 2 = 'I'B 
= 'O'B 

Bit 3 = 'I'B 
= 'O'B 

Bit 4 = 'I'B 
= 'O'B 

Bit 5 = 'I'B 

= •b'B 



Bit 6 = 'I'B 
= 'O'B 

Bit 7 = 



reserved; must be set to 
•0*B 

drifting S in subfield 
no drifting S in subfield 

drifting + in subfield 
no drifting + in subfield 

drifting - in subfield 
no drifting - in subfield 

drifting $ in subfield 
no drifting $ in subfield 

total suppression in 

subfield 

no total suppression in 

subfield 

* in subfield 
no ♦ in subfield 

reserved; must be set to 
•0*B 



Flag Byte 4 (describes the exponent 
subfield) 

Same format as Flag Byte 3. 

Inte;rnal codes fpr.„pictur eg 

Code Picture Code Picture 



00 


9 


48 


" (t) 


04 


Y 


4C 


- (d) 


08 


Z 


50 


- (s) 


OC 


* 


54 


$ (t) 


10 


E 


58 


$ (d) 


14 


K 


5C 


$ (s) 


18 


T 


60 


/ (t) 
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IC 


I 


64 


/ 


(d) 


20 


R 


68 


/ 


(s) 


2U 


CR 


6C 




(t) 


28 


DB 


70 




(d) 


2C 


B 


74 




(s) 


30 


S (t) 


78 


,- 


(t) 


34 


s (d) 


7C 




(d) 


38 


S (s) 


80 




(s) 


3C 


+ 


84 


V 




HO 


+ (d) 








HH 


♦ (s) 








(t) 


= terminal 








(d) 


= drifting 








(s) 


= static 









drifting, if: 

a. It is in a subfield containing 

either one or more Z or asterisk, 
or more than one +s, -s, or $. 



and if; 



b. It is not immediately preceding a 
Y, 9,, V, T, I, or R. In this case 
it is translated into terminal 
form. 



PEP for PROGRAM CONTROL Data 
Note; After E or K, the next byte contains 
the number of digits in the exponent, 

12 
Scale Factor r t 

1 Flag I Flag | 
The scale factor of a picture PEP is the jbyte 1 jbyte 2| 

number of digit positions after the 'V (0 l ■• 

if there is no 'V*) added to the number in 

the F specification, if any. Flag byte 1 = Hex 80, 84, 88, 8C, 90, 94, 

98, or 9C 
Rule for setting_bit5_in_Flag Bytes 3 
and 4 " 



Bit 5 is set if no 9, Y, T, I, or R is 
present. This applies before any Z, S, 
etc. has been translated to a 9. 

Rules for. translating pictures into encoded 
pictures 

1. Characters 9, Y, E, K, T, I, R, CR, 
DB,, B, and V are translated directly. 

2. Characters Z and ♦ are translated 
directly if they do not follow a V. 
If either follows a V,, it is 
translated into the code for character 
9. 

3. An S, ♦, -., or $ is translated to a 
static S, +, -,, or $ if it is the only 
one of its kind in the subfield. 

4. If more than one S appears in a 
subfield, the S*s are translated into 
drifting S*s, 

Except when: 

a. It appears immediately before a Y, 
9, V, T, I or R. In this case it 
is translated into the code for a 
terminal S. 

It appears anywhere after a V. In 
this case it is translated into 
the code for a 9. 



FORMAT PEPS - FEDS 



For meaning of flag bytes see above under 
Data Element Descriptors. 



DED for F and E FORMAT Items (FED) 



b. 



The same rule applies for the ♦, -, or 



I Flag I Flag | W | D | X | 
I byte 1 I byte 2 | j | | 

L J 

Flag byte 1 = Hex 50 

W = total length of the format field 

D = number of decimal places 

X = precision + 128 for F-format number of 
significant figures for E-format 



DED for PICTURE FORMAT Arithmetic Items 
(FED) 



1 2 3 4 

^ ^ 

1 Flag I Flag | W | copy of DED as for | 
jbyte 1 jbyte 2 j jarith. picture j 

L J 



5. 



or a 



is treated as Flag byte 1 = Hex 54 
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W = total length of the format field 



PEP. for PICTURE FORMAT character Items 

1 2 3 U 

r 1 

1 Flag I Flag | W | copy of PEP as for | 
I byte 1 I byte 2 j | pictured character | 

L J 

Flag byte 1 = Hex 58 

W = total length of the format field 



PEP for CONTROL .FORMAT Items (FEP) 

12 U 

r 1 

1 Flag I Flag (parameter | 
I byte 1 (byte 2 j | 
L J 

Flag byte 1 = Hex 60, 64, 68, 6C or 70 

Parameter = length of item (X format) 
column number (COL format) 
number of lines to skip (SKIP 
format) 

line number <LINE format) 
is omitted for PAGE format 



PEP for C FORMAT Items (FEP) 



PEP for STRING FORMAT Items (FEP) 



12 4 

^ . ^ 

1 Flag I Flag | W | FEP for | FEP for j 

1 byte 1 I byte 2| jreal part jimag. part | 

t . J 

Flag byte 1 = Hex 5C 

Note: The complex bit (bit 7) in flag byte 

2 is set in both the real part and the 
imaginary part FEP. 

W = total length of the format field 







i Flag I Flag | length | 
I byte 1 I byte 2 | | 

L J 

Flag byte 1 = Hex 58 

The difference between A, B, and P 
(character) formats is given by bits and 
1 of flag byte 2. The length field may be 
omitted for A and B format items. 
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Declare Control Block (DCLCB) 



Function 

Addresses file via PRV, holds declared file 
attributes, filename, and address of ENVB. 

When Gene r a te d 

During compilation. 

Where Held 

In separate control section for external 
files, or static internal control section 
for internal files. 

How.. Addressed 

Address generated by linkage editor for 
external files addressed by an offset from 
register 3 for internal files. 



10 



8 


16 


2U 


DFCB 


DCLA 


DOPA 


DENV 


reserved 


1 


DNMO 


DNML 


|DNAM(up 


to 31 chars) 



DFCB A(FCB) or Pseudo-Register offset (in 
first 2 bytes) 

DCLA Declare Attributes 

Byte_Number Hexadecimal_Value Attributes 



STREAM 

RECORD 

DISPLAY 

reserved 

(STRING) 

SEQUENTIAL 

DIRECT 

TRANSIENT 

INPUT 

OUTPUT 

UPDATE 

BACKWARDS 

BUFFERED 

UNBUFFERED 

KEYED 

EXCLUSIVE 

PRINT 

reserved 



Attributes which would conflict on 
OPEN. Format as for DCLA 



DENV A (Environment Block) or zero 

DNMO Offset in DCLCB of DNML 

DNML Length of File name 

DNAM File name (up to 31 characters) 



1 


01 




02 




04 




10 


2 


01 




02 




OH 




10 




20 




UO 




80 


3 


01 




02 




OU 




08 




10 


^ 




DOPA 


Attribut 
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Diagnostic File Block (DFB) 



Function 



Holds information used by the error message 
routines. 



When Generated 



During program initialization. 



AFLA 
ABTS 
ASPD 
AOCL 
ASDC 



Flags I Reserved 
A (transmitter) 
ACSYSPRINT DCLCB) 
A (EXPLICIT OPEN) 
A (Improvised Sy sprint DCB) 



T 

H 

8 

C 

10 



Where Held 



AFLA - Flags 



Program management area. 

How _Addressed 

From X'40' in the TCA. 



AWTO Bit 0=1 Messages going to operator's 

console 
ASNO Bit 1 = always 
ASCO Bit 2=1 SYSPRINT cannot be opened or 

open with unsuitable 

attributes. 
AFPF Bit 3=1 Force page 
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Dynamic Storage Area (DSA) 



Function 

Holds housekeeping information, automatic 
variables, and temporaries for each block. 



When Generated 



During execution. Allocated by prologue 
code every time a new block is entered. 



Where Held 

In the LIFO storage stack. Certain library 
routines have their DSAs in library 
workspace (LWS). See below 

How Addressed 

From register 13. 

Flags 

Bit = DSA in LWS 
1 DSA 

Bit 1 = No ON Cells 
1 ON cells 

Bit 2 = No Dynamic ONCBs 

I Dynamic ONCBs 

Bit 3 Always set to zero. 

Bits 4 and 5 

= 00 Procedure DSA 
01 Begin DSA 
10 Library DSA 

II On- unit DSA 

Bit 6 = Not a dummy DSA 
1 Dummy DSA 

Bit 7 unused. 

Bit 8 = always zero 

Bit 9 = Do not restore NAB on GOTO 
1 Restore NAB on GOTO 

Bit 10 = Do not restore Current-enable 
on GOTO 
1 Restore current-enable on GOTO 

Bit 11 = Callee cannot use this DSA 
1 Callee can use this DSA 

Bit 12 = Not an EXIT DSA 
1 EXIT DSA 

Bit 13 = No statement # table 

1 statement # table available 



10 
14 
18 
IC 
20 
24 
28 
2C 
30 
34 
38 
3C 
40 
44 
48 
4C 
50 
54 
58 
5C 
60 
64 
68 
6C 
70 
74 



1 Flags 


1 Offset 


1 Chain Back 


1 Unused 


1 Save area 


R 14 


1 Save area 


R 15 


1 Save area 


R 


1 Save area 


Rl 


1 Save area 


R2 


1 Save area 


R3 


1 Save area 


R4 


1 Save area 


R5 


1 Save area 


R6 


1 Save area 


R7 


1 Save area 


R8 


1 Save area 


R9 


j Save area 


RIO 


1 Save area 


Rll 


1 Save area 


R12 


1 A (LWS) 


1 Segment* | 


NAB 


1 Segment* | End 


of Prologue NAB 


1 Block-Enable Cell | Current-Enable Cell 


1 Static backchain 


1 A (First Static ONCB) 


1 A (most recent Dynamic ONCB in Block) 


1 Reserved 


1 Reserved 


1 Reserved 


1 A (ONCELLS) 


ICEXQ 1 // 1 


Flags 2 | CT flags 
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■l!lags_continued 

Bit 14 = 1 sysprint ENQ'd 

1 Flags 2 valid 





If the DSA is in LWS, offset is the 
offset of the ONCA. Otherwise, this field 
is not used. 

CEX2 

Save area for flag byte 1 of the TCA. 
Used if DSA is an exit DSA. 



Fla 

1 Last PL/I DSA 
1 Ignore DSA for SNAP 
1 ILC DSA after interrupt 
1 Invocation Count in this DSA 
Reserved 
Bit 5=1 There are TSO line numbers 

CT , (Control Task) Flags 

Bit 0=1 Block has active subtasks 

Note: This flag byte is the only one in 
the DSA used by the control task without 
synchronising with the subtask. The 
subtask must never change it. This 
prevents interference between CPU's on a 
multiprocessing machine. 
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Dump Block (DUB) 



Function 



To hold information about the dump file. 



When Generated 



During program initialization. 



Where Held 



In the program management area. 



How Address* 


ed 




From offset 



X*120' in the TIA. 

8 16 2t» 




r^ 


Flag. 


3 1| Flags 2| Reserved 


T 


ADCB 1 




A(DCB) 




ABUF 1 




A(Buffer) 




ADXT 1 




A (Dump Transmitter) 




ALNN 1 




Current line number 




APGS 1 




Pagesize 


1 


1 Reserved | 


1 Reserved | 


ASYN 1 




A(PLIDUMP SYNAD Exit) 


1 

J 



Flags 1 

ANDE Bit 0=1 Dump file cannot be opened 

Fla gs 2 

ANSS Bit = 1 No subtasks* subpools 
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Entry Data Control Block 



How Addressed 



Function 



Depends on the storage class of the data 



Holds the addresses of the data item and 
its DSA. 



When Generated 



When the variable is allocated. 



Where Held 



Depends on the storage class of the data 
item. 



4 

r ■ ' 1 

I Address | 

, 1 

4 I Address of statically containing | 
I DSA at time of assignment | 

L J 

Word 1: bit 0=0 Address of entry 

= 1 Address of location 
containing 8-char. 
EBCDIC name of entry 
point 

Word 2: bit always = 
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Environment Block (ENVB) 



7 Unused 



Function NFLC 

Holds environment options for a file so 
that the file may be correctly opened 
during execution. 

When Generated 

During compilation 

Where Held NFLD 

In a control section with the DCLCB for 
external files. In static internal storage 
for internal files. 

How Addressed 

From offset X'C* in the DCLCB 

8 16 24 (bits) NFLE 



H 
8 
C 
10 
14 
18 
IC 
20 
24 
28 



NFLA 


|NFLB 


INFLC 


|NFLD 


NFLE 


|NFLF 


|NFLG 


|NFLH 


NFLI 


INFLJ 


1 




NBLK 


NREC 


NBUF 


NLOC 


NKYL 


NNDX/NOFF 


NADD/NNCP 


NPAS 



NFLA consecutive 

1 indexed 

2 regional (1) 

3 regional (2) 

4 regional (3) 

5 tp(m) 

6 tp(r) 

7 Other organization see NFLH 

NFLB 

Bits 6 1 

10 Fixed 

01 Variable 

11 Undefined 
Bit 2 D or TRKOFL 

3 Blocked 

4 Spanned 

5 CTLASA 

6 CTL360 



NFLF 



NFLG 



NFLH 

NFLI, 

NBLK 

NREC 

NBUF 

NLOC 

NKYL 

NNDX 
NOFF 

NADD 

NNCP 

NPAS 



LEAVE 

1 REREAD 

2 GENKEY 

3 COBOL 

4 NOWRITE 

5 INDEXAREA 

6 TOTAL 

7 INDEXAREA with no argument 



BUFFERS 

1 NCP 

2 Unused 

3 KEYLENGTH 

4 KEYLOC 

5 VERIFY 

6 NOLABEL 

7 ADDBUF 



Unused 

1 Unused 

2 Unused 

3 Unused 

4 SCALARVARYING 

5 ANSCII 

6 BUFOFF 

7 BUFOFF (L) 



reserved 

F-format 

1 V-format 

2 U-format 

3 Spanned 

4 Blocked 

5 Unused 

6 Unused 

7 Unused 

VSAM 
1-7 Reserved 

NFL J reserved 

A(blocksize) 

A (record length) 

A (number of buffers) 

A (KEYLOC value) 

A (KEYLENGTH) 

A (INDEXAREA size) 
A (BUFOFF value) 

A (size of ADDBUF) 

A(NCP value) 

A (password string locator) 
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Event Table (EVTAB) 



How Addressed 



Function 



Used by ^JAIT module as workspace and to 
provide status information on associated 
event. 



When Generated 



During execution. 



From an offset from register 13. 
4 

r 1 

I (see below) 



U j chain field through EVTABs 



8 I A (Event variable) 



C |A(ECBLIST element) 

L 



WECB 
WECH 
WAEV 
WAEL 



Where Held 



In LIFO storage. 



WECB Bit set when event is complete 

Bits 1-7 Not used in this 
implementat i on 
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Event Variable Control Block 



Function 



To hold information about the operation 
with which the EVENT has been associated. 



H 

8 

C 

10 

lU 



Flagsll Flags2 


1 


STATUS 


Anchor for 


ECB 


chain 


A(ECB)/A(CCB) 


A(TCA appendage 


for 


I/O) 


A(FCB) 


Not used 



When Generated 



Depends on the storage class of the event 
variable. 



Where Held 



Depends on the storage class of event 
variable. 



S2S_^^ll£§ssed 

As other variables depending on storage 
class. 



Flags 1 

Bit =0 Incomplete 
1 Complete 

Bit 1 =0 Inactive 
1 Active 

Bit 2 =0 Not an I/O EVENT 
1 I/O EVENT 

Bit 3 =0 Not a DISPLAY EVENT 
1 DISPLAY EVENT 

Bit U =0 EV has not caused on-unit entry 
1 EV has caused entry to an 
on-unit 

Bit 7 ^always zero 

Flags_2 

Bit =0 No chain of ECBs 

1 Chain of ECBs exists 

Bit 1 =0 Not a dummy EVENT 
1 Dummy EVENT 
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Exclusive Block lOCB (XBI) 



First two words unused 



Function 

Locks individual records on exclusive 
files. 

When Generated 

By transmitter when required 

How Addressed 

From offset X'24» in lOCB and offset X'14' 
in the TIA. 



XIQE Start of ENQ LIST for system X'FF* 



XIQL Length of RNAME 



XIQS System flags must be X'Ul' 



XIQC Return code from system 



XIQA Address of QNAME (XFIO) 



r ~ ~ 

j .——____ 


reserved 




1 — 

H 1 XILA 
1 _i_.— ._. 


IXILE 


1 XILC 


1 

81 XIQE 

i .———._- 


IXIQL 


IXIQS IXIQC 


1 

C| 
1 «__ 


XIQA 




101 

1 ——___,__ 


XIRA 




1 

14 1 

1 -._——_-. 


XIIO 




1 
1C| 

1 «._-._—- 


XIVS 




1 

22 1 

1 •—.—.—. 


XIDS 




4E| 

1 ——_.—_- 


XIRN 




501 

L 


XIKY 





XIRA Address of RNAME (XFVS) 



XIIO QNAME CSYSIBMIO') 



XIVS RNAME of volume serial no. (part 1) 



XIDS RNAME of DSNAME (part 2) 



XIRN region no. in binary right adjusted 



XIKY RNAME of key .(part 3) 

Length of XIKY is keylength of data set 
restricted such that volume serial 
no. I |dsname| |key < 255 ISAM 

251 regional 
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Exclusive Block File (XBF) 



XFTK A(TCA) 



Function 

Identifies data set when locking for 
exclusive I/O. 

When Generated 

By the open routine 

How Addressed 

From offset X'74« in FCB. 



r 

0| 
1 « . 


XFTK 






U 1 XFLA 


IXFLE 


1 


XFIL 


8 1 XFQE 

1 i..— __— - 


IXFQL 


IXFQS 


IXFQC 


1 

1 —___-.-.- 


XFQA 






1 

10| 


XFRA 






14 1 

1 —-._._-.— - 


XFIO 






1 

1C| 

1 .——._—,. - 


XFVS 






1 

22| 

1 __—_-._- 


XFDS 






4E| 

L 


XFKY 







First two words reserved 



XFLA First flag byte 

Bit 0=1 Locked 

Bit 1 = 1 No DEQ required 

XFLB second flag byte (reserved) 

XFIL Length of exclusive block attached 
to lOCB 

XFQE Start of ENQ LIST for system X'FF» 

XFQL Length of RNAME 

XFQS System flags must be X'41' 

XFQC Return code from system 

XFQA Address of QNAME (XFIO) 

XFRA Address of RNAME (XFVS) 

XFIO QNAME CSYSIBMIO') 

XFVS RNAME of volume serial no. (part 1) 

XFDS RNAME Of DSNAME (part 2) 

XFKY RNAME of key (part 3) 

Length of XFKY is keylength of data set 
restricted such that volume serial 
no. I |dsname| |key < 255 ISAM 

251 regional 
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File Control Block (FOB) 

Function 

Used to access all file information. 
Contains addresses of the ENVB,DTF, 
filename, etc. 

When_Gene rated 

By the open routines during execution. 

Where_Hgld 

In subpool 1. 

How Addressed 

From two byte PRV offset which is held at 
offset X'O' in DCLCB. The PRV address is 
held at offset X«4' in the TCA. 

Comrnon Section 

1 2 3 4 



Flags showing valid statement types 
(FFST) 



8 
C 
10 
14 
18 
IC 

20 
24 
28 
2C 
30 
34 
38 

3C 
40 
44 
48 



A (invalid statement module) (FAIS) 



A (library transmitter) 



(FATM) 



A (DCLCB) 



(FADL) 



A(DCB)/A(ACB)VSAM 



(FADB/FACB) 



A (open file chain) 



(FAFO) 



A (data management for 
in-line I/O) 



(FAIL) 



FERR 






FCOM 




FATA 


1 


FATB 


FATC 


1 FATD 


FFLA 


1 


FFLB 


FFLC 


1 FFLD 


FFLE 


1 


FFLF 


FFLG 


1 FFLH 


Block 


size 


(FBKZ) 


Key length (FKYL) 



Record length 



(FRCL) 



A (first free lOCB) 

or 
A (Hidden buffer for 
QISAM LOCATE) 



(FAFR) 
(FREC) 



FTYP 



FLEN 



reserved 
reserved 



reserved 



FFST Flags indicating types of statement 
(8 bytes) 

lit_nuiriber Statement * options 

READ SET 

1 READ SET KEYTO 

2 READ SET KEY 

3 READ INTO 

4 READ INTO KEYTO 

5 READ INTO KEY 

6 READ INTO KEY NOLOCK 

7 READ IGNORE 

8 READ INTO EVENT 

9 READ INTO KEYTO EVENT 

10 READ INTO KEY EVENT 

11 READ INTO KEY NOLOCK EVENT 

12 READ IGNORE EVENT 

13 WRITE FROM 

14 WRITE FROM KEYFROM 

15 WRITE FROM EVENT 

16 WRITE FROM KEYFROM EVENT 

17 REWRITE 

18 REWRITE FROM 

19 REWRITE FROM KEY 

20 REWRITE FROM EVENT 

21 REWRITE FROM KEY EVENT 

22 LOCATE SET 

23 LOCATE SET KEYFROM 

24 DELETE 

25 DELETE KEY 

26 DELETE EVENT 

27 DELETE KEY EVENT 

28 UNLOCK KEY 
29-63 Reserved 



FERR 

X'02' 

X'03' 

X'lA' 

X'lC 

X'lD' 

X'lE' 

X»1F' 

X'Ol' 

X*04' 

X'05« 

X'06' 

X'07« 

X'08« 

X'09' 

X'OA* 

X'OB* 

X'OcC" 

X'OD' 

X'OE* 

X'OF* 

X'lO' 

X'll' 

X«12' 

X'13' 

X«14' 

X'15» 

X'16' 

X'17» 

X'18' 

X»19' 



Error codes 

INPUT TRANSMIT (DATA SET) 

OUTPUT TRANSMIT (DATA SET) 

OMR READ ERROR 

INPUT TRANSMIT (INDEX SET) 

OUTPUT TRANSMIT (INDEX SET) 

INPUT TRANSMIT (SEQUENCE SET) 

OUTPUT TRANSMIT (SEQUENCE SET) 

END OF FILE 

ZERO LENGTH RECORD VARIABL 

SHORT RECORD VARIABLE 

LONG RECORD VARIABLE 

KEY CONVERSION IN CHAR STRING 

KEY DUPLICATION 

KEY SEQUENCE 

KEY SPECIFICATION (NULL KEY) 

KEY NOT FOUND 

NO SPACE FOR KEYED RECORD 

NO lOCB AVAILABLE 

ACTIVE EVENT 

NO PRIOR READ BEFORE REWRITE 

NO COMPLETED READ BEFORE REWRITE 

PERMANENT OUTPUT ERROR 

ZERO LENGTH RECORD READ 

REC. REFERENCE OUTSIDE DATA SET 

UNIDENTIFIED 10 ERROR 

INCOMPLETE READ FOR UPDATE 

TP TERM ADDR SPECIFICATION 

DIFF FCB SAME RECORD REQUEST 

KEY CONVERSION (NEG BIN NO) 

KEY SPECIFICATION (X'FF* ETC) 
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X'lB' I/O SEQUENCE ERROR 

X«20' SYNAD ERROR ENCOUNTERED 

X'21' RECORD LENGTH < KEYLEN + RKP 

X'22' RECORD ALREADY HELD 

X*23' RECORD ON NON- MOUNTED VOLUME 

X'2U' DATA SET CANNOT BE EXTENDED 

X»25' NO VIRTUAL STORAGE FOR VSAM 

X'26' NO KEYRANGE FOR INSERTION 

X«27' NO POSITIONING FOR SEQL READ 

X'28» ATTEMPT TO REPOSITION FAILED 

FCOM Reserved for future releases for 
compatibility flags. 

FTYP 6th and 7th characters of library 
transmitter name 



FFLC 



3 REGIONAL (2) 

4 REGIONAL (3) 

5 TP(M) 

6 TP(R) 

7 Other organization 

Hex Contents 





8 

OC 

10 

14 

18 

IC 



QSAM 

BSAM 

BSAM(Load) 

TCAM 

QISAM 

BISAM 

BDAM 

VSAM 



FLEN Length of FCB 

FATA-FATD Flags showing attributes 

allowable with file types, and 
other file usage information. 



FFLD 



FATA 



FATB 



FATC 



FATD 



FFLA 



FFLB 



Bit 



Attribute 






Open SYSPRINT for error 




message 


1 


SYSPRINT 


2 


unused 


3 


String operation 


t\ 


unused 


5 


unused 


6 


RECORD 


7 


STREAM 





BACKWARDS 


1 


UPDATE 


2 


OUTPUT 


3 


INPUT 


4 


unused 


5 


TRANSIENT 


6 


DIRECT 


7 


SEQUENTIAL 





unused 


1 


unused 


2 


unused 


3 


PRINT 


4 


EXCLUSIVE 


5 


KEYED 


6 


UNBUFFERED 


7 


BUFFERED 



FFLE 



FFLF 



FFLG 



all unused 



Bit 






F- format 


1 


V- format 


2 


U- format 


3 


Blocked 


4 


Spanned 


5 


unused 


6 


unused 


7 


Key in record 




variable KEYLOC 





CONSECUTIVE 


1 


INDEXED 


2 


REGIONAL (1) 



FFLH 



Bit 


1 
2 
3 
4 
5 
6 
7 


1 
2 
3 
4 
5 
6 
7 


1 
2 
3 
4 
5 
6 
7 


1 
2 
3 
4 
5 

6 
7 


1 
2 
3 
4 
5 

6 
7 



Paper tape 

Printer 

Unit record device 

The Foreground Terminal 

ENDFILE module loaded 

Possible hidden buffer 

Error module loaded 

Genkey 

I/O error 

permanent input error 

permanent output error 

end of file 

hidden buffer in use 

move required 

non-SCALARVARYING 

reserved 

previous READ 
previous READ SET 
previous LOCATE 
previous REWRITE 
previous OPEN 
close in progress 
implicit close 
previous OPEN (resume load) 

ENDPAGE 

end of extents 

COPY option active 

reserved 

checkout transmitter 

checkout compiler step end 

flag 

newly opened print file 

file not to be closed 

In-line I/O 
In-line locate 
hyphen at end of line 
retry get after concat 
current line unfinished 
initial call from IBMBSPL/ 
blanks at end of record 
new buffer wanted 
GET prompt issued - input 



The common section is followed by either 
the RECORD or STREAM sections. 
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Record I/O Section 



Note: Offsets are from start of the FCB. 







HC 

50 
54 

58 
5C 
60 

64 

68 
6C 
70 

74 
78 

7C 



A (last lOCB used) 

or 
A(DAMT buffer for LOCATE) 



A (first lOCB to be checked) (BSAM) 



Static chain of lOCBs 
(BDAM/BISAM/BSAM/VSAM) 



AdOCB for last completed read) 



FEMT 



FEFT 



FRET 



FAFB 



A (error module) when loaded 

or 
A (bootstrap) which loads it 

(IBMBRIOB) 



FFNC JFELV or | 
I FFNF I 



FKLO or FLCT 



reserved 



A (dummy key area) 



Size of lOCB (BDAM/BISAM) 

or 
Current relative block (BSAM) 



A (exclusive block FILE) 



Table of offsets used in 
record checking 



Base OPTCD for RPL (VSAM) 



DCB prefix (associated files) 
Data Management DCB 



FALU 
FCDA 
FACK 
FIOC 

FALR 
FERM 



FCCT 
FAKY 
FIOS 
FREL 
FXBA 
FRTB 

FAWB 



FRET Data management return code (regional 
output ) 



FEMT 6th char of error module name 



FEFT 7th char of endfile module name 



FAFB Work byte for associated files 



FFNC Function byte 



Bit READ file 

1 PUNCH file 

2 PRINT file 

3 OMR (no other lists on) 

4 R in FUNC option 

5 P in FUNC option 

6 W in FUNC option 

7 Associated file 



FFLV VSAM flags 



Bit KSDS 
1 ESDS 
2-7 reserved 



FCNF conflict byte 



Bit prior READ invalid 

1 prior PUNCH invalid 

2 prior PRINT invalid 

3 prior PRINT last line invalid 
4-7 reserved 



FKLO KEYLOC-1 



FLCT Decrementing line count 
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stream I/O Section 



Offsets are from the start of the FCB, 



4C 
FREM 50 

FPGZ 54 

FLNN 58 

5C 

60 
6*4 

68 
6C 



r 

1 A (next 


available 


byte 


in a buffer) 


1 Bytes remaining 
1 buffer 


in 1 
1 


Value of count 
built-in function 


j Page size 


1 


Line size 


1 Current line no. 


1 


Record size 


1 A (copy 
1 A ( next 


position in buffer) 

or 
TPUT position) for OUTPUT 


1 A(DCLCB for COPY 


file 


) 


1 A (copy 


module in 
output. ) 


put/tab module 


1 Reserved 


L„ 


FSCB 







FCBA 
FCNT 

FLNZ 
FMAX 
FCPM 
FNTP 
FCPF 
FCPA I FTAB 
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Flow Statement Table 



Function 



Used to iirplement the coinpiler FLOW option, 
Holds the last *n* statement number pairs 
and the last 'm* procedure names executed. 
Cn* and 'm* are programmer defined.) 



When Generated 



Storage is allocated during initialization 
if the FLOW option has been specified. The 
table is continually updated as the program 
is executed. 



Where Held 

In initial storage area. 

How Addressed 

From offset X'4C» in the TCA. 



ACHK Bit 4 unused 
AGTO Bit 5 Unused 

ATKC Bit 6 The next in entry is in new 
task 
1 



ARGT 



AFLL 
ANEN 

AASB 



10 

m 



18 
ANEB IC 



AAEB 
ASBS 
AFLI 



20 

2a 

28 



Code to access IBMBEFL to 
initialize flow table for 
subtasks. Called when bit 6 in 
AFLF is set. 



Total length of the table 



A (next free field in stmt, no 
sect. ) 



A (start of names section of 
table) 



A (next free field in names 
section) 



A (end of table) 



A (start of number section) 



Flag 
Byte 



AFLG- Flags 

Reserved 

AFLl-Flaq 

Bit = 1 No statement numbers requested in 
flow trace (e.g. FLOW(0,20)). 
1=1 Last entry was in. 
2=1 Used by Checkout Compiler only. 
3=1 Interrupt not recorded. 
4=1 GOTO-out-of -block has occurred. 



AFLF - Flags 



ATBI 


Bit 





ABCD 


Bit 


1 


ATXT 


Bit 


2 


ADUM 


Bit 


3 



Branch-in entry 

BCD form for this entry 

BCD in text reference form 

Dummy entry after on-unit exit 



ASBD 



r ' 

1 AFLF lAFLG 
1 Flag |Flag 
1 Byte 1 Byte 


1 Statement 

1 

1 


1 Number 


lAFLF 
iFlag 
JByte 


lAFLG 
IFlag 
JByte 


1 Statement Number 




1 Names of blocks 
1 8 characters 


truncated to 


L 
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Interlanguage Root Control Block 
(IBMBILCl) 



Function 



Connects ZCTL and interlanguage VDA to 
interlanguage routines, and records state 
of activation of language interfaces. 



When Generated 



During compilation, 



Where Held 



In static internal storage, as a control 
section. 



How Addres s ed 

Address generated by linkage editor. 



12 3 

J. 

I Address of ZCTL 

4 I COBOL I FORTRAN |Task | 

flag I flag j locking! 

I I flag I 

L J 

Flags 

COBOL flag indicates COBOL is active in 
program 

FORTRAN flag indicates a procedure which 
called FORTRAN is active 

Task locking flag indicates that a task is 
accessing IBMBILCl 
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Interlanguage VDA 



How Addressed 



Function 



From offset X'O' in ZCTL. 



TO hold information required for 
interlanguage calls. Used for information 
that alters from invocation to invocation. 



When Generated 



One interlanguage VDA is generated for each 
interlanguage call made from PL/I to 
FORTRAN or COBOL. An interlanguage VDA is 
also acquired if the PL/I environment has 
not yet been set up when PL/I is called 
from COBOL or FORTRAN. 



I A (previous interlanguage 
I VDA or zero) 



I 

4 I Flags I Not used 
I 

8|A(Current DSA) 



C|A(Caller*s PICA) 

L 



Flags 



Where Held 



In the LIFO storage stack. 



Bit 0=1 If there is a previous call to 

COBOL 
1=1 If there is a previous call to 

FORTRAN 
2=1 If main procedure is not PL/I 
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Interrupt Control Block (ICB) 

Function 

Acts as a parameter list to IBMBERR. 

When Generated 

After an error has been detected. 

Where Held 

As a VDA in the LIFO stack. 

How Addressed 

Passed as parameter list to IBMBERR 
addressed by register 1- 



Condition qualifier = A(DCLCB) for I/O 

condition 

= A(CSECT) for 

CONDITION condition 

= A(SYMTAB) for CHECK 
condition 

= A(SYMTAB LIST) 



HLFG flags 






12 3 4 


r 

0| 

1 __—_—— 


Error code 


1 

1 -._-.— 


Condition Qualifier 


1 

8|DSA 

1 Level 

1 — _— .._ 


IHLFG flags 
1 


1 

c| 

1 _——_—— 


A (array element) 


101 

1 __-._— 


Reserved 


1 

L 


A (generation of variable) 



HLCD 
HLQU 
HLLN 

HLEA 
HLSY 



Bit 0=0 Reserved 



Bit 1=0 Element address not in list 
1 Element address in list 



Bit 2=0 CHECK is enabled 

1 CHECK enablement unknown 



Bit 3=0 Qualifier is not address of 
SYMTAB list 

1 Qualifier is address of 
SYMTAB list 



Bit 4=0 Not word 6 information 

1 Use word 6 to address the 
generation of variable being 
checked 
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Input/Output Control Block (lOCB) 



Where Held 



Function 

Used as a data management parameter list 
during certain record I/O statements and to 
hold information about statement type 
during the time between a record I/O 
statement and the associated WAIT 
statement . 

When Generated 

Either by the PL/I transmitter module 
(BISAM or BDAM) or by the OPEN module. 



In non-LIFO storage for VSAM, in subpool 
for BSAM (obtained by GETPOOL) , BISAM or 
BDAM (obtained in non-tasking » in subpool 
for tasking. 



How Addressed 



By fields in the FCB. lOCBs are chained 
together and the actual field used to 
address them depends on the type of 
statement being executed. 



Common Section 



8 
C 
10 

in 

18 

IC 

20 
L 



ICHN 




1 


INXT/IRGN 1 


IFLA 1 


IFLB 1 lERR 


1 
1 


IRCB 1 


lORD (1st 


word) 


1 

1 
- 1 


lORL 1 


lOKD/IREF 


(1st word)/IFNA 


1 


lOKL/IREF 


(2nd word)/IFBK 




lEVT 




-J 



> end of common section 

(second section starts here) 



ICHN Static forward chain 
INXT Chain of free or unchecked lOlbs. 
IRON Region no. left adjusted (BDAM) 
IFLA Flag byte - bits set to ■!• indicate: IRCB 
Bit = record locked lORD 

1 = record to move 

2 = varying string with non- lORL 

scalarvarying 

3 = lOCB in use lOKD 

4 = general error flag 

5 = dummy records being output lOKL 

6 = dummy buffer acquired IREF 

7 = lOCB checked 

IFLB Code byte containing offset within IFNA 

•look-up* table used for record 

checking IFBK 

lERR Error codes (as in FERR of FCB) first lEVT 



byte is for TRANSMIT, second byte for 

ENDFILE, RECORD, KEY 6 ERROR 

conditions. 

Request Control Block 

1st word of record description - 

Record address 

2nd word of record descriptor - flags 

and record 

1st word of key description - key 

address length by region number 

2nd word of KD - flags and key length 

Relative block in record numbers 

(2 words) (BDAM) 

Next address feedback (Regional 3, 

spanned) 

BDAM feedback (BDAM spanned) 

A (EVENT variable) 
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Second section for non VSAM files 



2ii 


lADE/IXLV/IRLB 


28 


ITIA 


2C 


lECB 


30 


ITYP 1 


ILEN 


34 


IDCB 


38 


IREC 


3C 


ISTS 1 


ILOG 


ao 


lADB/INLF/IKEY 


HH 


IBLK/IEXI 


48 


INDF/ISBF 


HC 


IDBF 

L.. - .— .^- . 



IRLB Binary region no. (Regional (1) Update) 

ITIA A (Iirplenientation Appendage) 

lECB Data management Event Control Block 

(BDAM exception codes in 1st 2 bytes) 
ITYP Type of I/O operation (set by Data 

management) 
ILEN Record length 
IDCB A(DCB) 
IREC A (buffer) if one exists on A (record 

variable) 
ISTS A (status indicators) (BSAM 6 BDAM) 
ILOG A (logical record) (BISAM) 
lADB A (dummy buffer) (BSAM) 
INLF A (next record feedback) — > IREF 

(BSAM) 
IKEY A (KEY) (BDAM S BISAM) 
IBLK A (relative block or record) i.e. A 

(IREF) (BDAM) 
lEXI BISAM exception codes 
INDF A (next record feedback) — > IREF 

(BDAM) 
ISBF Start of appended buffer (BSAM) 
IDBF Start of appended buffer (BDAM S 

BISAM) 



lADE A (ECB) for REGIONAL SEQUENTIAL ONLY 
IXLV A (Exclusive block) for direct only 
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Second section for VSAM files 



VSAM Section (starting at offset X'24') 



1 

24| 




IDUB 




1 


28 1 


IKSV 1 


2C| 


lEVC 1 


30| 


IMHD 1 


3H\ 


IMEL 1 


38 1 


1 1 


3C| 


1 1 


40| 


1 1 

V 1 


44 1 


ISHD 1 


481 


ISEL 1 


4C1 


IHTC 1 


50| 


IRPL 1 


54 1 


ISAR 1 


58 i 


ISLN 


1 


* 




5C 


1X34 


1 


* 




601 


lOPT 1 


64 


IX 2C 


1 


* 


1 
1 


68 


lARA 1 


6C 


IX 2D 


1 


* 


1 
1 


70 


lARL 1 


74 


1X35 


1 


* 


1 

1 


78 


IRCL 1 


7C 


1X38 


1 


* 


1 


80 


ISIK 1 


84 


IX 2E 


1 


♦ 


1 

1 


88 


lARG 1 


8C 




1X30 


1 


♦ 


1 


90 


IKYL 1 


94 





* 




1 



IDUB A (durnmy buffer) 
IKSV A (key save user) 
lEVC Data Management Event Control 
Block 



MODCB plist (5 words starting at offset 
X'30«) 

IMHD A (header entry) — > IHTC 
IMEL Element entry addresses (maximum 
of 4) 



SHOWCB plist (2 words starting at offset 

X'44») 

ISHD A (header entry) — > IHTC 

ISEL A (element entry) 



Header control entry (4 words starting at 

offset X'4C') 

IHTC header type code for MODCB | SHOWCB 

of RPL 
IRPL A (Request Parameter List) 
ISAR A (receiving area for SHOWCB) 
ISLN L (receiving area for SHOWCB) 



Element control entries start at offset 
X*5C* and continue to end of lOCB. Each 
entry occupies 2 words, with keyword type 
code set in 1st half-word as follows: 
IXab = X'OOab* 2nd word of each entry is 
used as either a setting field for MODCB 
or a receiving field for SHOWCB. The lOCB 
field names are lifted with their 
corresponding RPL (Request Parameter List) 
parameters. 



♦Reserved fields 



lOPT 


OPTCD 


lARA 


AREA 


lARL 


AREALEN 


IRCL 


RECLEN 


ISIK 


FDBK 


lARG 


ARG 


IKYL 


KEYLEN 
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Key Descriptor (KD) 



Function 



Contains address and length of key for 
passing to library record I/O routines. 



When Generated 



As far as possible during compilation, 
necessary, completed during execution. 



If 



Word 2 



Bit 



Bit 1 



•1»B if KEYTO string is 
VARYING. (If this bit is set, 
the I/O transmitters will set 
the current length field) . 

•I'B if word 3 contains a 
region number. 



Bits 2-15 Unused (zero) 

Bits 16-31 Length of key string 

(excluding length bytes for 
VARYING) ; current length for 
KEY or KEYFROM, maximum length 
for KEYTO. 



Where Held 



Normally in static internal control 
section. In static external control 
section if key is EXTERNAL. Will be copied 
into, or generated in, temporary storage if 
procedure is reentrant or recursive. 



Word_3 

Region number in fixed binary, right 
justified. 



How Addressed 

From an offset from register 3 known to 
compiler code for internal keys. 



r 

0| 

1 -.——«- 


A (Key String) 


1 j.^ — 

1 L L— — — ^. 


1 length 


1 I.L — 

8| 

L 


Region number 



Word 1 

KEYFROM s Address of source key (excluding 
the length bytes if VARYING) 

KEYTO; Address of where to put key 
(excluding length bytes if 
VARYING) 



304 



Label Data Control Block 



Label yariable_andLafcel,.teropgrary 



Function 



Holds the address of the data item and, if 
a label variable, the address of the 
associated DSA. 



When Generated 



Label constants; during compilation 
Label variables: when the variable is 
allocated depending on storage class. 
Label temporaries: When required for GOTO 
to label constant. 



(Address of label constant 
I assigned to label variable 



I Address of DSA (at tiire of 
I assignment) of owning block 



Word 1: bit 0=0 Address of label 
constant 

= 1 Text reference 

Word 2: bit always = 



Where Held 



Depends on the storage class of the data 
item 



How Addressed 
As a variable. 



Label Constant 



4 

r 1 

I Address of label | 
, , 

4 I Value to be loaded into | 

1 Register 2 on GOTO | 

t J 
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Library Workspace (LWS) 



Function 



Space reserved for two pre-formatted DSAs 
used by certain library modules. 



When Generated 



The first LWS is generated during program 
initialization. Subsequent LWSs are 
allocated before entry to any on-unit. 
This is because the on-unit may require the 
use of library modules using LWS but roust 
not alter the environment of the interrupt. 



2 


4 





r 
Flags (As DSA)| offset to 


ONCA 


H 


Housekeeping information 
DSA 


as for 


50 


56 bytes workspace 


88 


Flags (as DSA) | offset to 


ONCA 


8C 


Housekeeping information 
for standard DSA 


as 


D8 


56 bytes workspace 


110 


Current ONCA 

L. .- . 



Where Held 



First allocation in the program management 
area, subsequent allocations in the LIFO 
storage stack. ONCAs are generated with 
LWS. 



How Addressed 

From offset X'U8' in each DSA. 
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On Communications Area (ONCA) 



Function 



An area in which built-in function values 
or their addresses are placed, after the 
occurrence of a PL/I interrupt. 



When Generated 

The first ONCA is generated during program 
initialization. Subsequent ONCAs are 
generated with each allocation of LWS. 



Where Held 

Contiguous with LWS in the program 
management area and in the LIFO stack. 



How.Af^dressed 

By an offset from the current generation of 
library workspace. The offset is held as a 
halfword at offset X' 2* in LWS. 



The dummy ONCA has the same format as other 
ONCAs and holds default values for those 
condition built-in functions that have 
default values. 



Flags 1 
Bit 

Bit 1 

Bit 2 

Bit 3 

Bit t\ 

Bit 5 

Bit 6 

Bit 7 

Bits 8 



= ONFILE invalid 
= 1 ONFILE valid 

= ONCHAR/ONSOURCE invalid 
= 1 ONCHAR/ONSOURCE valid 

= ONIDENT invalid 
= 1 ONIDENT valid 

= ONKEY invalid 
= 1 ONKEY valid 

= DATAFIELD invalid 
= 1 DATAFIELD valid 

=0 No associated EVENT variable 
= 1 Associated EVENT variable 

= ONATTN invalid 
= 1 ONATTN valid 

= ONCOUNT invalid 
= 1 ONCOUNT valid 

-15 unused 



1 



r 
Chainback to previous 


1 

ONCA 1 


4 


ONCODE 1 


flagsl 1 


8 




string locator 

ONFILE 


for 1 


10 




string locator 
ONCHAR 


for 1 


18 




string locator 
ONSOURCE 


for 1 


20 




String locator 
ONKEY 


for 1 


28 


string locator for | 
DATAFIELD | 


30 


reserved j 


38 


A (record I/O EVENT variable) | 


3C 


reserved j 


40 


ONCOUNT 1 


HH 


retry environment j 


48 


retry offset j 


4C 


X«40' 


1 X'OOOO* 1 


flags2 1 


50 


LCTl 


ILRAC 1 


1 

Unused | 



LOCB 
LCDE 
LOFL 

LOCH 

LOSC 

LOKY 

LODF 

LEVT 

LCNT 
LREN 
LRAD 



Fla3S_2 
Bit 



Bit 1 



= ONSOURCE/ONCHAR not used in 

on-unit 

= 1 ONSOURCE/ONCHAR used in 

on-unit 

= ONSOURCE not set in ONCA 
= 1 ONSOURCE set in ONCA 



Bits 2-7 unused 

LCTl 

Copy of TCA flag byte 1 (TFBl) 

LRAC 

Retry address code 

Retry .of f set 

The offset from the base of the library 
module involved to the address at which a 
conversion will be reatteropted if ONSOURCE 
or ONCHAR has been used. 
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On Control Block (ONCB) 



static ONCB 



Function 



Contains pointer to associated on unit, or 
indicates action to be taken when interrupt 
occurs. 



H ow Addr essed 

From offset X*60* in the TCA. 



12 t^ 

J. ^ 

1 Code I Flags | Unused | 
I 1 

^ I Target | 

L J 

Qualifier 

A(FCB) for I/O conditions A(SYMTAB) for 
CHECK A(CSECT) for CONDITION condition. 



When Generated 



Code 



Static ONCBs are generated during 
compilation, one for each ON statement. 
Dynamic ONCBs are generated by the prologue 
code of the procedure or block in which the 
ON statement occurs, or are allocated in a 
VDA when the ON statement is executed. 



Where Held 



Static ONCBs are generated in the static 
internal control section. Dynamic ONCBs 
are stored in the DSA of the block in which 
the associated on-unit occurs. 



PL/I code for condition 



Flags 
Bit 



SYSTEM not specified 
1 SYSTEM specified 



Bit 1 = Not a null on-unit 
1 Null on-unit 



Bit 2 = Not a GOTO only on-unit 
1 GOTO only on-unit 



Static and__D;gnamic ONCBs 



Bit 3 = Condition not established 
1 Condition established 



Static ONCBs are generated for unqualified 
conditions. Dynamic ONCBs are generated for 
qualified conditions (ENDPAGE, ENDFILE, 
etc. ) 

Dynamic ONCB 



Bit 4 Unused 



Bit 5 = Condition not enabled at block 
entry 
1 Enabled at block entry. 



Address of previous dynamic ONCB 
in block (or zero, if first) 



Qualifier 



Code I Flags | Unused 



Target 



Bit 6 = Condition disabled 
1 Condition enabled 



Bit 7 = SNAP not specified 
1 SNAP specified 



Target 



Address of on-unit, or Offset in DSA of 
word containing A (label variable) 
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Open Control Block (OCB) 



NPA - Open attributes 



Function 



Used to indicate that a file attribute 
(either input or output) was declared in 
the associated OPEN statement* 



Wh§S_Generated 

During compilation, 

Wherejaeld 

Static internal control section. 

How Addressed 

From an offset from register 3 known to 
compiled code. 



4 

r ' 1 

Oj NPAA I NPAB I NPAC | NPAD 



This word indicates the explicit and 
implied attributes on the OPEN statement. 

Byte No. Hex. Valuei Attributes 



01 


STREAM 


02 


RECORD 


04 


DISPLAY 


10 


reserved 




(STRING) 


80 


Debug open 




of SYSPRINT 


01 


SEQUENTIAL 


02 


DIRECT 


08 


TRANSIENT 


10 


INPUT 


20 


OUTPUT 


40 


UPDATE 


80 


BACKWARDS 


01 


BUFFERED 


02 


UNBUFFERED 


04 


KEYED 


08 


EXCLUSIVE 


10 


PRINT 


20 


AXES 



8| 



NDEM 
Unused 



4 RESERVED 

NDEM - Open conflict njask 

This is a mask generated by the compiler 
containing bits for all attributes which 
conflict with those on the OPEN statement. 
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Ordered Delete List (ODL) 

Function 

Hold list of transient modules to be 
deleted during program termination. 

When Generated 

During program initialization. 

Where Held 

Program Management area. 

H ow Add ressed 

From offset X«38" in the TCA. 



This block is initialized to binary 
zeros; each routine places its address in 
the appropriate field as soon as it is 
loaded. 






^ . . « 

A(IBMBEDWA) 


^ 


A(IBMBEDTA) 


8 


A(IBMBKOTA) 


c 


A (Extended float simulator) 




10 


A(IBMBMYEA) 


lU 


A(IBMBMCTA) 


18 


A(IBMBSPCA) 


IC 


A(IBMBPESA) 


20 


A(IBMBCCLA) 


24 


A(IBMBSTAB) 


28 


A(IBMBEIIA) 

L ~ ^ 



310 



PLIMAIN 



Function 



Holds address of entry point of main 
procedure 



How Address (sd 

Address resolved by linkage editor. 

12 3 4 

r 1 

1 VCON (Primary entry point to program) | 
, , 

I zero I 

L J 



When__Generated 

During compilation of procedures with the 
MAIN option 



Dumroy_PI.IMAIN 



Where Held 

A separate control section in the load 
module 



A control section in IBMBPIR and IBMTPIR 
holding addresses of error message module. 
This control section is link- edited if no 
compiler generated PLIMAIN exists. 
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Record Descriptor (RD) 

Function 

To hold data about the record variable. 

When Generated 

During Compilation. 

Where Held 

Static control section. 

How Addressed 

From an offset from register 3 known to 
compiled code. 

1 4 

J. . ^ 

I A (record variable) | 
, I 

4 I length | 

L J 

Word_l 

1. Address of the data to be written out. 

2. Address of where data read in is to be 



3. 



put. 



LOCATE statement: Address of where to 
store buffer address. 



Word 2 



Bits - 7 indicate the type of INTO or 
FROM argument as follows: 

X'OO* for fixed length strings 
X'Ol* for area variables 
X*02' for varying length 

character strings 
X ' 03 ' for varying length bit 

strings 

Bits 8-31 length of data to be transmitted 
(length of variable or buffer 
for locate mode) . 

The value is in bytes for all 
strings including bit strings. 

For VARYING strings, the value 
includes the two length bytes, 
and is the current length for 
output operations and the 
maximum length for input 
operations . 
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Request Control Block (RGB) 



REQ2 (options) 



Function 



Used by the record I/O interface module 
(IBMBRIO) to check the validity of an I/O 
statement. The instruction in RTMI is 
carried out by IBMBRIO. 



X*80' 
X'40* 
X«20' 
X*02« 
X»01* 



INTO/FROM 

SET 

IGNORE 

NOLOCK 

EVENT 



RE23 (options) 



When Generated 



During compilation. 



Where Held 



X*80' - KEY 
X'lO* - KEYTO 
X«20' - KEYFROM 



Static internal control section. 



How_Addressed 

From an offset from register 3 known to 
compiled code. 



12 3 

r 1 

I REQl I REQ2 | REQ3 | REQ4 | 

, I 

4 I RTMI i 

L J 

REgl (statement identification) 

X'OO* - READ 

X'OU' - REWRITE 

X'08« - WRITE 

X*OC» - LOCATE 

X'lO' - DELETE 

X*1U' - UNLOCK 



RE^4 unused 



RTMI 



Either a TM or a BR instruction 
depending on source program. 

A TM instruction is used if the 
statement cannot be checked for validity 
during compilation, or if it has been 
checked and found to be invalid. 

TM instruction used by IBMBRIO for 
testing the validity of a statement. 

X*91MM2SSS' 

where MM is byte containing current 
statement bit and SSS is offset of 
corresponding byte in FCB statement mask. 

A BR instruction is used if the 
statement has been checked during 
compilation and found to be valid. 

Unconditional branch instruction to PL/I 
library or LIOCS transmitter. 
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Statement Frequency Count Table 



Function 

To retain a record of the number of times a 
statement has been branched to or from, for 
use by the COUNT option. 

When Generate d 

When the associated external procedure is 
entered. 

Where Held 

Non-LIFO storage. 

How Addressed 

The statement frequency count table for the 
first external procedure in a program is 
addressed from offset X*48' in the TCA 
appendage (TIA). The tables are chained 
together and the chain field of the last 
table set to zero. The chain field is at 
offset in the table. The most recently 
used table is addressed from X'4c' in the 
TIA. 



ACBS The address held in ACBS is the 
address of ACGS. If tables are 
segmented, second and subsequent 
sections of the table will start at a 
point equivalent to ACSG. 



ACFL Flags 
ACBI Bit 
ACGT Bit 1 



ACIA Bit 
ACNM Bit 

ACUI Bit 
ACZL Bit 



last update was for a branch 

in 

last update was for a GOTO 

out of block 

table inactive 

table is for procedure with 

GONUMBER option 

table is uninitialized 

table contains unexecuted 

ranges 



Other bits unused. 





4 

8 
C 

10 

14 

18 

IC 

20 



A (next table 



A (static CSECT OF PROCEDURE) 



name of procedure 



flags 



A (first segment) 



A (next segment) 



number of entries 



length of segment 



count entry or number 



count entry 



count entry or number etc 



ACTB 
ACST 
ACEP 

ACFL 
ACBS 
ACSG 
ACNG 
ACLG 
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Statement Number Table 



Line Number Format 



Function 



To relate statement numbers to offsets so 
that statement numbers may be given in 
execution-time messages. 



When Generated 



During compilation, if the GOSTMT option is 
in effect. 



Where Held 



static internal control section. 



How Addressed 

From offset X'8* from entry point of main 
procedure. 



When line numbers are generated they are 
held in 6-byte fields. The first 27 bits 
hold the line number, right adjusted in 
binary. The last five bits hold the number 
of the statement on the line, again right 
adjusted in binary. 



The presence of line numbers is 
indicated by bit 5 of Flags 2 in the DSA 
being set to 1. The validity of Flags 2 is 
indicated by bit 15 in the flags in the 
first two bytes of the DSA being set to 1. 
The presence of line numbers is indicated 
if both these flags are set to 1. 



♦ = End of first section 



Sections of Table 



Because offsets are held in two bytes and 
the value may in fact take up to three 
bytes (4096), it is necessary to hold the 
table in sections. 



Statement Number Format 

Halfword binary right-aligned. 

2 ^ 

r * 1 

I A primary entry point of block 



U jsize of code generated for block 
I in bytes 



A (start of second section) 



Offset 



Statement No. 



Offset I Statement No. 
A (end of second section of table) 



Offset I Statement No, 
Etc. 



Offset: Offset is the offset of the first 
byte of the statement relative to 
the address of the primary entry 
point of the block. If the offset 
is more than X'7FFF' the statement 
number will be held in the second 
or subsequent sections of the 
table. Obtain the number given by 
translating the offset into binary 
and ignoring the last 15 bits and 
step down this number of sections 
of the table. (For example, if 
the offset was X'8FFF», translate 
to binary = 'lOOO 1111 1111 
1111 'B, ignore last 15 binary 
digits =1, therefore step down one 
section of the table. If the 
offset was X'lSFFF' the binary 
would be '0001 1000 1111 1111 
1111 'B. Ignoring the 15 right hand 
bits leaves "ll'B therefore step 
down three sections of the table.) 



The address of the second section of the 
table is held at offset X'8* in the table, 
the address of the third section is held at 
the head of the second section, the address 
of the fourth section at the head of the 
second section and so forth. 
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Storage Report Table 



TRFG FLAGS 



Function 



To hold the information from which a 
storage report will be generated. 



When Generated 



During program or task initialization 



Where Held 



Program management area, or for major task 
in storage associated with the control 
task. 



How^_Addressed 

From X'38' in the TIA. 

Non-multitasking and_ PL/I task table 


H 
8 



C 
10 

in 

18 
IC 
20 
24 
28 
2C 



r ' ** 

1 True EOS value 


|Used ISASIZE 


|TRFG Specified ISASIZE 
1 flags 


1 ISA adjustment 


1 Extra storage required 


1 Number of GETMAINs 


1 Number of FREEMAINs 


1 Number of get non-LIFO requests 


1 Number of free non-LIFO requests 


1 Current extra storage owned 


1 Current unused ISA 


1 Address of tasking appendage 
1 (multitasking only) 

L 



•lOOOOOOO'B Major task table 



•OlOOOOOO'B Update complete (get 
LIFO) 
Control task table 





0| 




4| 




3| 




c| 




10| 




14 1 


task 


18 1 




1C| 




20| 




24 1 




28| 


1 


2C| 


ITRES 
1 




1 

JTRUS 

1 


30| 


1 
ITRSS 




1 
1 


34| 


1 
ITRUN 




1 


38 1 


ITREX 
1 




1 

JTRGM 

1 


3C| 


1 
ITRFM 




1 


40| 


ITRGN 
1 




1 

JTRFN 

1 


44| 


1 
JTRCS 




1 


48| 


ITRUI 
1 




1 
JTRTT 

1 


4C| 



Major task - Used ISASIZE 



Major task - Specified ISASIZE 



Major task - ISA adjustment 



Major task - Extra storage required 



Major task - Number of GETMAINs 



Major task - Number of FREEMAINs 



Major task - Number of get non-LIFO 
requests 



Major task - Number of free 
non-LIFO requests 



Subtasks - Max ISASIZE used by any 
subtask 



Subtasks - Min ISASIZE used by any 
subtask 



Subtasks - Specified ISASIZE all 
subtasks 



Subtasks - Max storage required any 
subtask 



Subtasks - Min storage required any 
subtask 



Subtasks - Max extra storage any 
subtasks 



Subtasks - Min extra storage any 
subtasks 



Subtasks - Total number of GETMAINS 
all subtasks 



Subtasks - Total number of 
FREEMAINs all subtasks 



Subtasks - Total number of get 
non-LIFO requests all subtasks 



Subtasks - Total number of free 
non-LIFO requests all subtasks 



Maximum number of PL/I tasks 
attached 



CSMU 
CSMI 
CSMN 
CSMX 
CSMG 
CSMF 
CSMH 

CSMJ 

CSXU 

CSNU 

CSSI 

CSXN 

CSNN 

CSXX 

CSNX 

CSSG 

CSSF 

CSSH 

CSSJ 

CSNA 
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stream I/O Control Block (SIOCB) 



Function 



Holds addresses of source and target, 
source and target DEDs etc and is used as 
parameter list by stream I/O routines. 



When Generated 



During execution for the duration of the 
stream I/O statement. 



Where_Held 

In temporary storage. 

How__Addressed 

Passed as parameter list by compiled code. 



SSRC 
SSDD 
STRG 
STDD 

SFCB 
SRTN 
SAVE 

SCNT 

SOCA 

SSTR 






Address of source or its locator 


4 


Address of source DED 


8 


Address of target or its locator 


C 


Address of target DED 


10 


SFLG 1 STYP 1 SDSA | SDFL 


m 


Address of FCB for file 


18 


Address of next statement 


ic 


Save word used in compiler 
generated subroutines 


20 


Value of COUNT | Unused 
built-in f unctn. 1 


24 
28 


Address of ONCA 




Area used during GET or PUT string 
to hold dummy FCB. 

L 



Flag Byte SFLG 

Bit 0=1 Transmit on input 

Bit 1=1 VDA used in edit-directed input 

Bit 2=1 IBMBSED is used 

Bit 3=1 call to IBMSIST required after 

dealing with next item (Stream I/O 
only) 

SDSA 

DSA level number (used only for data- 
directed I/O) 

Type code STYP 

Bit 0=1 data-directed I/O 

Bit 1=1 list-directed I/O 

Bit 2=1 edit-directed I/O 

Bit 3=1 string I/O 

Bit 4=1 CHECK entry to data-directed 
I/O 

Bit 5=1 input 

Data-directed flag SDFL 

Bit 0=1 Terminating call to data- 
directed output 
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String Locator/Descriptor 



Function 



F = '0* B Fixed string (First bit of 
second byte) 
' 1 ' B Varying string 



Used to pass the address and the length of 
strings to other routines. Also for 
handling strings with adjustable lengths 
(e.g., DCL STRING CHAR (N)). 



F2 Used for bit strings to hold offset 
from byte address of first bit in 
string (3 bits) 



When Generated 



Storage reserved during 
compilation. Fields completed during 
execution if string has adjustable length. 



Allocated_len2th 



For varying strings this is the declared 
length. Length is held in bits for bit 
strings and in bytes for character strings. 



Where Held 



Static internal control section. 



How Addressed 

From an offset from register, 3 known to 
compiled code. 

1 2 3 4 

r ■" 1 

1 Byte address of string | 
, „ I 

4j Allocated length |F| unused F2 | 

L ^ J 



String Descriptor 



The string descriptor is the second word of 
the string locator/descriptor. It appears 
in structure descriptors and in the 
description field of controlled variables. 
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Structure Descriptor 



General Format 



Function 



contains information about the offset of 
each element within a structure, and the 
nature of each element. Used when passing 
a structure to another routine, or for 
accessing structure elements during 
execution, if the structure is declared 
with adjustable extents or with the REFER 
option. 



When Generated 



If the structure has no adjustable 
elements, during compilation. If the 
structure has adjustable elements, during 
execution from information held in the 
aggregate descriptor descriptor,. 



Where Held 



Static internal control section. 



For each base element in the structure, a 
fullword field containing the offset of the 
start of the element from the start of the 
structure is given. If the base element is 
a string, area, or array, this fullword is 
followed by the offset field for the next 
base element. 



Offset of element from start 
of structure 



Descriptor of element if 
element requires descriptor 



Offset of element from start 
of structure 



Descriptor of element if 
element requires descriptor 



etc 



For every base element in 
the structure, an entry is 
made consisting of an 
offset field and, if the 
element requires a descrip- 
tor, a descriptor. 



Offset 



How^Rddressed 

From an offset from register 3 known to 
compiled' code. 



The offset field is held in bytes,. Any 
adjustments needed for bit-aligned 
addresses ar.e held in the respective 
descriptors. 
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Symbol Table (SYMTAB) 



Bit 3 = 'I'E EXTERNAL 
= 'O'B INTERNAL 



Function 



Holds the name of the variable during 
execution and associates it with the 
address of the variable. Used only when 
data-directed I/O or the CHECK condition is 
specified. 



Bit 4 = 'I'B item may appear in some 
CHECK list 

= *0'B item appears in 
no CHECK list 

(Bit H must be 'I'B if item is EXTERNAL). 

Bit 5 = 'I'B Address field A refers to data 
= 'O'B Address field A refers to 
locator 



When Generated 



During compilation, if data-directed I/O or 
the CHECK condition is used in the program 



Where Held 



Static internal control section for 
internal names. Separate control section 
for external names. External control 
sections consist of the name followed by an 
♦ . 



HoW-Addressed 

from an offset from register 3 for internal 
data, by an address generated by the 
linkage editor for external data. 



8 
C 
10 



Flags 1 

1 


Dimension | Level 
ality 1 number 


A(DED) 


Address field A 


Address field B | 


Address field C 


Length of name | 




Name (fully qualified) 



Flags 

Bits 0,1 S 2 = •OOO'B STATIC 

= "lOO'B AUTOMATIC 

= ■ 010 'B CONTROLLED 

(not par am. ) 

= •OOl'B BASED 

= 'Oll'B DEFINED 

= "lOl^B a non-CONTROLLED 

parameter 

= •lll'B a CONTROLLED 

parameter 



(Bit 5 must be 'O'B for a CONTROLLED 
parameter) 

Bit 6 = 'I'B a member of a structure 

= 'O'B not a member of a structure 

Bit 7 = 'I'B Normal SYMTAB 

= 'O'B Short SYMTAB (has fields A, B 
and C omitted) 

Bit 8 = 'I'B Address field A addresses code 
= 'O'B Address field A does not 
address code 



Bit 10 



Always set to 



Bits 11 - 15 reserved; must be set to 
'O'B. 

Dimensionality 

The number of dimensions declared for an 
array item. Dimensionality is zero for 
other items. 

Level number 

(for AUTOMATIC, DEFINED, and BASED 
items. Also for all parameters.) The 
level of the block in which the variable 
is declared. The level of a block is 
one greater than the level of the 
immediately containing block; the level 
of the external block is 0. 



Address Fields 



Addresses are held in different formats for 
different data types. As far as possible, 
addresses are held in address field A. 
However, more information than can be held 
in a fullword field is sometimes required, 
when this is the case, address fields B and 
C are used. 

Address ..field A 

If STATIC Address of data or address of 

locator for items that have 
locators . 
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If AUTOMATIC Offset within the associated 
DSA of the data or of the 
locator for items that have 
locators. 

If CONTROLLED Offset of the data or its 

locator from the address in 
the anchor word. 

If BASED Offset of field within DSA 
containing address of 
declared pointer qualifier. 

If PARAMETER or DEFINED Offset of one word 
field in associated DSA 
containing address of 
corresponding argument, or 
DEFINED data, or its locator. 
For CONTROLLED parameters, the 
argument is its anchor word. 

Address f ield, B Used for CONTROLLED and 
BASED items only. 

If CONTROLLED Address of anchor word, 

either in static internal for 
internal data or in a separate 
CSECT for external data. 

If BASED see below. 



zeros. 

Address field C Used for BASED and 

structure elements only. 

If STRUCTURE (Not BASED Structure) Offset 
from start of structure 
descriptor to field that holds 
offset of element from start 
of structure, see "structure 
Descriptor. " 

If BASED STRING, BASED STRUCTURE, BASED 
ARRAY, or BASED AREA, For 
all items except structures^ 
fields B and C hold the offset 
(right justified) of the 
descriptor from the start of 
the DSA in which it is held. 
For structured items, the 
offset is to the offset word 
in the structure descriptor. 
This word holds the offset of 
the item from the start of the 
structure, see "Structure 
Descriptor" . 

Other data Not used for other data types. 
Set to a null value of all 
zeros. 



Other data Not used for other data types. 
Set to a null value of all 



Length Length is the number of characters 
in the fully qualified name. 
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Symbol Table Vector 



How Addressed 



Function 



From an offset from register 3 known to 
compiled code. 



Holds addresses of symbol tables and 
associates them with the block in which the 
associated names were declared. 



When Generated 



During compilation, 



Where Held 



Static internal control section. 




r" 


A (symbol 


table) 






A (symbol 


table) 






full word 


of zeros 






A (of entries in symbol table 
of encompassing block) . All 
for main procedure block 


vector 
zeros 


L. 




etc. 





General Format 



The format of symbol table vector is a 
series of fullwords. These contain either: 



1. 
or 
2. 

or 
3. 



The address of a symbol table 



The address of the entry in the symbol 
table vector of the start of the 
entries for the encompassing block. 



A fullword of zeros indicating the end 
of the current block. 



< — marks end of 
block. 
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Task Communications Area (TCA) 

Function 

Acts as a central communications area for 
the program. Contains addresses of 
essential routines and control blocks, and 
various flags. (See chapter 5). 

When Generated 

During program initialization by IBMBPIR. 

Where Held 

In the program management area at the head 
of the initial segment area (ISA). 

How Addressed 

From Register 12 

1 2 3 U 



10 

m 

18 

IC 

20 

2U 

28 

2C 

30 

34 

38 

3C 

40 

TORC 
44 

48 

4C 



TFBO I TFBl 



TFB2 I TFB3 
A(PRV) 



Segment #| BOS 

I Beginning of Segment 
I Pointer 



Segment #| EOS 

I End of Segment Pointer 



Unused 
A (current event variable) 



A (External Save Area) 
A(TRT Table) 



Task Level 
A (Current Task Variable) 



A (TCA appendage) 

A (Tasking Appendage) 



A (Save Area for Overflow Routine) 
Open File Chain Anchor 



A(C 


)rdered 


Delete 


List) 




Unused 




A(Diagnost 


ic File 


Block) 


PL/I 
Code 


Return 


1 
1 


User Return 
Code 


A (Overflow 


Routine 


for Get 


VDA) 



A (Flow stmt number table) 



TPRV 
TBOS 

TEOS 



TESA 
TTRT 
TTIC 
TTSK 
TTIA 
TTTA 
TPSA 
TFOP 
TOOL 
TBUG 
TDFB 
TURC 

TOW 
TSFT 



50 
54 
58 
5C 
60 
64 
68 
6C 
70 
74 
78 
7C 
80 

F4 

F8 

FC 

100 

104 

108 

IOC 

110 
114 
118 

lie 



A (Tab table) 



A (Flow module) 



A(LPA Module - Region) 



A(LPA Module - LPA) 



A(LPA Module - LPA) 



PRV Initialization Word 



Unused 



A (Get Dynamic Storage Routine) 



A (Free Dynamic Storage Routine) 



A (Overflow Routine for Get DSA) 



A (Error Handler) 



Environment Description 



Normal GOTO Code 
Used when GOTO out of block iray 
occur 



A (Interpretive GOTO routine) 



A (Get control routine) 



A (Free control routine) 



Dummy ENQ routine field 



Dummy DEQ routine field 



A (WAIT routine) 



A (COMPLETION pseudovariable 
routine) 



A (EVENT assign routine) 



A (Priority routine) 



A(ENQ/DEQ routines) 



Reserved for users 



TTAB 
TEFL 
TPSR 
TPSL 
TPSM 
TPRI 

TGET 
TFRE 
TOVF 
TERR 
TENV 
TGTC 

TGTM 
TGCL 
TRCL 
TEQR 
TDQR 
TAWT 
TACP 

TAEA 
TAPR 
TEDR 
TUSR 



TENV Is a field used to define PL/I library 
modification level. 

TRLR is the resident library release 
number, 

TTLR is the transient library release 
number. 

TUSR Is a field reserved for the use of 

programmers using the PL/I Optimizing 
and Checkout compilers. Any user 
routine may use this field as a base 
for addressing. 
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TFLG contains flag bytes TFBO, TFBl, TFB2, 
and TFB3. 

Flag Byte - TFBO 

TTIS Bit = Major Task 1 Siabtask 

TTTT Bit 1=0 Program will not multitask 
1 Program may multitask 



TTCK Bit 2 = 



Reserved 



TTFT Bit 3=0 Not eldest task from 

attaching DSA 1 Eldest task 

TTFD Bit 4=0 No daughter tasks exist 1 
Daughter tasks exist 

Note; This flag byte is the only one in 
the TCA used by the central task without 
synchronising with the subtask. The 
subtask must never change it. This 
prevents interference between CPU's on a 
multiprocessing machine. 

Flag Byte 1 - TFBl 

TGFD Bit 0=0 No daughter tasks 1 At 

least one daughter task may 
exist 



TGFE Bit 1 



TGFV Bit 2 = 



No active EVENT I/O ON 
units 1 At least one active 
EVENT I/O ON unit 

unused 



TGFS Bit 3=0 SORT routine inactive 1 
SORT routine active 

TGNQ Bit 4=0 SYSPRINT not ENQed 1 

SYS PRINT ENQed by this task 



Bit 5=1 Task ending 



Ela3_Bzte_2 - TFB2 

THQS Bit 0=0 Do not raise SIZE for 

fixed-point divide, fixed- 
point overflow, exponent 
overflow, or decimal overflow 

1 Raise SIZE if one of these 
exceptions occurs 

THQI Bit 1=0 Do not ignore fixed-point 
divide, fixed-point overflew 
or exponent overflow 1 Ignore 
any of these exceptions 

Bits 2-4 Reserved 



Bit 5 



= 1 File associated with SIZE 



THQR Bit 6=0 Normal action on normal 

return from on-unit 1 Return 
to caller after normal return 
from on-unit 



THQC Bit 7 = 



Not I/O Conversion 1 
Conversion 



I/O 



Flag Byte 3 - TFB3 

TMDF Bit = Reserved 



Bit 1=0 


Prompt required 


= 1 


Prompt not required 


Bit 2 = 


Reserved 


Bit 3 = 


Reserved 


Bit 4 = 


Reserved 


Bit 5=0 


Not implied SKIP next 


= 1 


Implied SKIP next 


Bits 6-7 


Reserved 
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TCA Appendage (TIA) 



Function 



To hold control and communication 
information. 



When Generated 



During program initialization. 



Where Held 



Program management area. Addressed from 
offset X'28' in the TCA. 



How Addressed 

From X*28* in the TCA. 




H 
8 

c 

10 

14 

IC 
20 
24 
28 
2C 
30 

38 
3C 
40 
44 

48 
4C 
50 



12 3 
A (Byte beyond ISA) 
A (Old PICA) 



A (Interrupt Handler) 



Interrupt Mask | Flagsl | Flags2 
WIT Chain Anchor 



Anchor for chain of 
exclusive blocks 



A (Last free area) 
A (Dump Block) 



A (Dummy DSA) 

A (Get LWS code) 

A (Extended float simulator) 



Two_wgrds for name of 
extended float simulator 



A (Storage for report info.) 
Chain of fetched entry points 
A(Stae Exit routine) 



A (Housekeeping interrupt routine) 
(ERRC) 



A (first count table) 

A (last count table used) 

A (TCA) , used by error handler 



TISA 
TAPC 
TERA 
TINM 
TWTW 
TEXF 

TLFE 
TDUB 
TDDS 
TLWR 
TASM 
TSNM 

TASR 
TFEP 
TAST 
TERC 

TCTF 
TCTL 
TATC 



Flagsl - TFLl 



TELA Bit 

TFLS Bit 1 

TFLJ Bit 2 

TFLK Bit 3 

Flags2 

TFLD Bit 

TFLR Bit 1 

TFLT Bit 2 

TFLP Bit 3 

TFLX Bit 4 



1 Task terminated normally 
1 SYSPRINT open 
1 STAE exit in progress 
1 Dump I/O in progress 



• 1* B caller provided ISA 
'I'B storage report required 
•1«B STAE required 
'I'B SPIE required 
'I'B Syntax error in program 
management options 
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TCA Tasking Appendage (TTA) 



Post Codes to Control Task 



Function 

To hold control and communication 
information used in multitasking programs 

When Generated 

During program initialization. 

Where Held 

Program Management area. 

S2w_Addressed 

From X*2C' in the TCA. 



Completion pseudovariable 

H EVENT assignment 

8 PRIORITY pseudovariable 

12 I/O EVENT completion 

16 WAIT termination 

20 Detach this block 

24 Dedicate control task 

28 Liberate control task 




C 

io 

14 
18 
IC 
20 

2H 

28 
2C 
30 



POST ECB 


PLIST 


for Control Task 
(2 words) 


WAIT ECB 


A(TCB) 


AtECBLIST element) 


A (TCA) 


Reserved 


Chain 


of sister tasking 
appendages 


Anchor 


for subtask sister 
chain 


Anchor 


for I/O EVENT chain 


A (Attaching DSA) 


A (task 


invocation point) 



TPEC 
TCTP 

TWEC 
TTCB 
TAEE 
TTCA 

TSIS 

TSUB 

TIOE 
TDSA 
TALR 
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Task Variable (TV) 

Function 

To hold inforiration about task 

When Generated 

Depends on storage class 

Where Held 

Depends on storage class 

How Addressed 

From offset X'2U' in the TCA. 

12 3 4 

J. ^ 

OjFlagsl |Flags2 | Priority | 

, 1 

4 1 A(syMTAB) I 

, I 

8 1 A (TCA Tasking Appendages) | 

I , , 

CJ A (calling PROCEDURE) | 

L J 



Flagsl 

Bit 0=0 Inactive 1 Active 

Flagsg 

Bit = Not a duitimy 

1 Dummy 

Bit 1=0 Symbol table does not exist 
Symbol table exists 
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Wait Information Table (WIT) 



How Addressed 



From X'lO' in the TIA. 



Function 

Used to hold information about a WAIT 
statement 

When Generated 

When the WAIT statement is initiated 

Where Held 

In the LIFO stack 



Chain Back 
A(EVTAB) 



I 

8|A(Byte beyond EVTAB) 



WCHB 



j WAET 

I 

I WABT 



C| 



Reserved 
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Zygo-lingual Control List (ZCTL) 



Function 



To hold information required for 
interlanguage calls. Holds information 
that does not change for every invocation. 



When Generated 



On the first interlanguage call, 



Where Held 



In the LIFO stack if PL/I is main 
procedure. If COBOL or FORTRAN are 
principal procedures, at the head of the 
unused portion of the region immediately 
before the TCA. 



How Addressed 

From offset X'O* in IBMBILCI. 



10 

18 

24 
28 
30 



A (latest interlanguage VDA) 
or zero 



Flag I 
Byte I 



A (PI/I PICA) 



A (COBOL PICA) 



A (FORTRAN PICA) 



COBOL INTERS PICA 

(2 words) 



FORTRAN INTER=^ PICA 
(2 words) 



A(TCA) 



A(TCA appendage) 



Save Area 1 (22 words) 

Used by IBMBIEPA and IBMBIEFA 



A (PL/I STAE Exit routine) 



Ghost Save Area (U words) 



Save Area 2 (18 words) 
Used as DSA when principal 
procedure not PL/I 



Save Area 3 (18 words) 

Used internally by IBMBIEPA 

if principal procedure not PL/I 



^ The "INTER PICA" is a PICA used if the 
INTER option is specified. 

Note: Beyond offset X*30* only the save 
areas needed are acquired. 

When the first call is made from PL/I to 
COBOL, only the first 30 bytes are 
acquired, the first 30 bytes plus save 
area are acquired. 

When the first call is made from COBOL 
or FORTRAN to PL/I, the complete area shown 
is acquired. 

Flags 

Bit = 1 If there is a previous call to 
COBOL 
1 = 1 If there is a previous call to 
FORTRAN 

6=1 STAEs will be issued STAEs not 
issued 
7=1 SPIES will be issued SPIEs 
not issued 

Bits 3, U and 5 unused 
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Index 



abnormal SOTO 30 

code in TCA 70 

library subroutine IBMBPGO 30 
abnormal termination (multitasking) 266 
access method 

record I/O 127 

stream I/O 153 
activating blocks 24 
actual origin (AO) 53 
address constants 17 
addressing beyond UK limit 21 
aggregates 23 

(see also structure; array) 

address 53 

arrays of structiires 23 

COBOL 250 

descriptor descriptor 57,274 

FORTRAN 250 

interlanguage argiaroents 233,250 

locator 54-56,275 
alignment in structures 250 
alignment requirements 18 
ALL built-in function 191 
allocation of storage 75-85 
AND logical operation 191 
ANY built-in function 191 
AO (actual origin) 53 
areas 

address 54-56 

control block 273 

descriptor 272 

locator/descriptor 54-56,272 

storage management 84 
arguments lists 30 
arrays 

assignments 23 

descriptor 276 

descriptors 23 

FORTRAN 250 

implementation of 23 

in stream I/O 174 

interlanguage communication 233 

interleaved 190 

of structures 23,54-56 
arrays of structures 23 

arrays 23 

assignments 23 

implementation of 23 
ASSEMBLER - PL/I communication 251 
ASSEMBLER option 251 
attaching a task 264 
attributes , data 53 
AUTOMATIC variables 19 

in dump 226 

storage 76 



backchains 

dynamic 26 

static 26 
base element 54-56 
base registers 

DSA pointer 17 

program base 17 

static base 17 

TCA pointer 17 
BASED storage 20,75 
BASED variables 20 

in dump 226 

storage 75 
beginning of segment (BOS) pointer 69 
BIT data 

string assignment subroutine 
(IBMBBGF) 191 

unaligned strings 189 
block enable cells 100 
blocks 

activation 24 

termination 24 
BOOL built-in function 191 
BOS (beginning of segment) pointer 69 
bounds, adjustable 53 
branches, rationalization of 38 
buffer pointers (stream I/O) 156 
built-in functions 

arithmetic 18 9 

array handling 189 

condition 97 

DATE 192 

library subroutines 189 

mathematical 18 9 

stream I/O 174 

string handling 18 9 

structure handling 189 

TIME 191 



C format item DED 281 
CALL statements 26 
CALL. ..TASK failure 266 
calling trace 

following through dump 219 

obtaining 210 
chain, free-area 71 
CHECK condition 105 
CHECK prefix 105 
checkpoint/restart facility 197 
CLOSE statement 143,127 
closing files 

explicit closing 143,127 

implicit closing 143 

library subroutines 143 
COBOL 

COBOL-PL/ I communication 242-246 

option in ENVIRONMENT attribute 251 

structure mapping 250 
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COBOL (continued) 

ZERODIVIDE on- unit 246 
COLUMN format option 171 
common expression, elimination 34 
cortiinoning 36,38 
commun icat ion 

between languages 231-253 

between routines 53-66 
compare-aligned-bit-string subroutine 

(IBMBBBC) 191 
compare-unaligned-bit- strings subroutine 

(IBMBBGC) 191 
compilation 1 
compile-time DED 57 
compiler generated subroutines 33 
compiler options 

AGGREGATE 12 

ESD 12 

FLOW 12 

LIST 12 

MAP 12 

OFFSET 12 

SOURCE 12 

STORAGE 12 
compiler output 11-38 

compiler-generated subroutines 168,179 
COMPLETION built-in function 198 
COMPLETION pseudovariable 198 
completion values, multitasking 268 
concatenate-character- strings subroutine 

(IBMBBCK) 191 
CONDITION condition 107 
conditions 

default values 97 

defaults 89-90 

enablement 89-90,105 

general 97 

implementation in general 93-108,93 

name abbreviations in dump 210 

record I/O 145,144 

values in dump 219 
consecutive buffered files 127,146 
constants 18 
constants pool 18 
control blocks 

formats 271-3 29 

locating in dump 227 
control format items 168 

DED 28 0,281 
control sections 11-38 
control task 

general 255 
controlled variable block 20 
CONTROLLED variables 20 

control block 277 

header information 20 
conversational files 177 
conversion 181-189 

CONVERSION condition 188 

hybrid 187 

in-line conversions 185 

library subroutines 181-182 

multiple 187 

ONCA 175 

ONCHAR function/pseudovariable 175 

ONSOURCE function/pseudovariable 175 

stream I/O 160 
CONVERSION condition 174,188 



COUNT function 174 
COUNT option 120 
CSECT (control section) 
current enable cell 99 



11-38 



data 

internal representation 181 

interrupt 88 
data element descriptor (DED) 
formats 278-281 
general description 57 
data format item 168 
data interrupt 8 8 
data list matching 169 
data set interchange between PL/I and 

COBOL 251 
data-directed I/O 168-169 
DAT AFIELD built-in function 174 
DATE built-in function 192 
DCLCB see declare control block 
decimal overflow interrupt 103 
declare control block (DCLCB) 

format 282 

general 125,127 
DELAY statement 192 
dequeuing on SYSPRINT 270 
descriptors 53-62 

aggregate descriptor 
descriptor 54-56,274 

area 54-56,27 2 

array 54-56,276 

string 54-56,318 

structure 54-56,319 
detatching a task 266 
DFB (diagnostic file block) 107,283 
diagnostic file block (DFB) 108,283 
diagnostic statement table (DST) see 

statement number table 
director routines in stream I/O 160 

list of 179 
disablement of conditions 99 
DISPLAY statement 192 
DO loops 32 
DST (diagnostic statement table) see 

statement number table 
DUB (dump block) 286 
dummy arguments in interlanguage 

communication 250 
dummy DSA 72 
dummy FCB 22 
dummy ONCA 

chaining 97 

description 71 

format 307 

introduction 71 
dummy sections 21 
dump block (DUB) 286 
dump control module (IBMBKMR) 109 
dump debugging procedures 212,215 
dumps 

contents 210 

debugging with 205-228 

file 112 

implementation 109-112 

obtaining 207 

options 207 

subroutines that generate 109 
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dynamic backchain 26 

dynamic descendency 87 

dynamic ONCB 100 

dynamic storage area (DSA) 75-85 
associating DSA with block 219 
contents for compiled code DSA 25 
dummy 72 

format and function 28 U 
forward chain in dump 224 
IBMBERR*s DSA in dump 213 
initialization 65 
uses 7 5 



E format item DED 280 
ECB list 264 
edit-directed I/O 169-174 

arrays 174 

compiler-generated subroutines 179 

control format items 168 

data format items 168 

FED 16 8 

format DED 168 

format list 168 

format option handling 173 

GET statement 168 

library director modules 178 

matching data and format lists 173 

non-matching data and format lists 173 

PUT statement 168 
element, base 53 
element, structure 53 

elimination of unreachable statements 36 
enable cells 99 
enablement of conditions 99 
enablement status 28 
end of extent, offset to (OEE) 85 
end of file 145 

end of segment (EOS) pointer 69 
END statement 27 
ENDFILE condition 

detecting 96 

record I/O 14 5 

stream I/O 174 

summary information 88 
ENDPAGE condition 88 

enqueuing on SYSPRINT (reason for) 270 
ENTRY data control block 287 
entry points 

addresses in dump 218 

conversion subroutines 182 

library subroutines 40-50 

load module 11 

main procedure 11 
ENTRY statement in interlanguage calls 231 
environment 

definition 3 

FORTRAN 233 

initialization 65-69 

interlanguage communication 238 

SORT 192 
ENVIRONMENT attribute COBOL option 251 
environment block (ENVB) 

format 288 

record I/O 128 

stream I/O 154 
EOS (end of segment) pointer 69 
epilogue code 24 



epilogue code (continued) 

example 26 
error codes, list of 211 
ERROR condition 88,211 

on-unit and dumps 215 
error handling during execution 87-121 

error code 97,211 

error handling subroutine 
IBMBERR 102,107 

error message modules 107 

event I/O 140 

finding the block entry-point 
address 107 

FORTRAN 247 

record I/O 14 5 

stream I/O 174 
error identification 

address in dump 218 

using dump in general 205-228 
ESD records 

definition 11 

for conversion modules 182 
established on-units 100 
event control block (ECB) 256-257,202 
event I/O 132-13 5 
event table (EVTAB) 2 89 
event variables 197,290 

control block format and function 290 
exclusive block lOCB (XBI) 291 
exclusive file block (XBF) 292 
exclusive I/O 140 
execute interrupt 88 
execution time options 

handling 68 

PLIXOPT 68 
exit table, SORT 197 
explicit open 

stream I/O 153 
exponent overflow interrupt 88 
exponent underflow interrupt 88 
extent, offset to end of (OEE) 85 
external conversion director modules 180 
EXTERNAL data 65 
external reference, weak(WXTRN) 44 



F format item DED 280 

FCB see file control block 

FCBA field in FCB 156 

FCPM field in FCB 175 

FED (format element descriptor) 

format 280-281 
FEFT field in FCB 145 
FEMT field in FCB 145 
FERM field in FCB 145 
fields, locating in dump 227 
file control block (FCB) 128 

FCBA field 156 
17 5 
145 
14 5 
145 

fields for buffer operation 156 

format and function 293-296 

FREM field 156 

general description 128 

record I/O 29 5 

stream I/O section 296 



FCPM field 
FEFT field 
FEMT field 
FERM field 
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filenames 127 
files 

addressing 21 

closing 143,127 

conversational 177-178 

declaration 125,127 

declaration with COBOL option 251 

exclusive 1U3 

filename 127 

implicit opening 144,127 

information in dump 211 

opening, explicit 128 

record variable 13 
FINISH condition 69,90 
fixed-point data 

binary 181 

decimal 181 

DED 27 9 
FIXEDOVERFLOW condition 88 
floating-point data 

binary 181 

decimal 181,185 

divide interrupt 88 

underflow interrupt 103 
floating-point registers 

saving 103 

usage 19 
FLOW compiler option 118-121 

library subroutine IBMBEFL 114 
flow of control 24-30 
flow statement table (FST) 

format 297 
format element descriptor (FED) 

description 61 

format and function 280 
format items 173 
format list matching 173 
format option handling 171 
formatting modules in stream I/O 180 
formatting, conversational files 177 
FORTRAN interrupt 247 
FORTRAN- PL/I communication 246-248 
free control routine 266 
free decimal 184 
free-area chain 79 
freeing storage 75-85 
FREM field in FCB 156 
function references 27 
fundamental in-line conversions, list 
of 185 



get control routine 266 
GET DATA Statement 

implementation in general 160,168-169 

symbol tables and symbol table 
vectors 61 
GET LIST statement 168 
GETIME macro instruction 192 
GOTO only on-units 30 
GOTO statement 27-29 

label variable 29 

out of block 28 

within block 28 



hardware interrupts see program check 



interrupts 
hexadecimal dump module (IBMBKDO) 109 
hierarchy of tasks 255 
hybrid conversion 188 



I/O 

record 125-151 

stream 146 

stream conditions, detecting 96 

IBMBAAH 1 91 

IBMBAIH 189-190 

IBMBAMM 1 91 

IBMBANM 191 

IBMBAPC 191 

IBMBAPE 191 

IBMBAPF 1 91 

IBMBAPM 191 

IBMBASC 1 91 

IBMBASE 191 

IBMBASF 1 91 

IBMBAYE 191 

IBMBAYF 191 

IBMBBBA 191 

IBMBBBC 1 91 

IBMBBBN 191 

IBMBBCI 1 91 

IBMBBCK 191 

IBMBBCT 191 

IBMBBCV 191 

IBMBBGB 191 

IBMBBGC 191 

IBMBBGF 1 91 

IBMBBGI 191 

IBMBBGK 1 91 

IBMBBGS 191 

IBMBBGT 1 91 

IBMBBGV 191 

IBMBEFL 118-121 
IBMBERR 

DSA in dump 213 

general 102-106 

IBMBESM 106-109 

IBMBESN 106-109 

messages 106-109 

IBMBIEC 242-246 

IBMBIEF 246-248 

IBMBIEP 248-250 

IBMBILCl (interlanguage root control 

block) 238,298 

IBMB JWT 1 98 

IBMBMXE 190 

IBMBMXL 190 

IBMBMXS 190 

IBMBMXW 190 

IBMBMXY 190 

IBMBMXZ 190 

IBMBMYE 190 

IBMBMYL 190 

IBMBMYS 190 

IBMBMYX 190 

IBMBMYY 190 

IBMBMYZ 190 

IBMBOCA 126 

IBMBOCL 126 

IBMBOPA 126 

IBMBOPB 126 

IBMBOPC 126 
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IBMBPAF, controlled variable allocation 20 

IBMBPAM 8 5 

IBMBPEP - exceptional error message 

director 112 
IBMBPEQ - NO MAIN PROCEDURE message 112 
IBMBPER - NO STORAGE message 112 
IBMBPES - ABEND analyzer 112 
IBMBPET - abnormal interrupt message 112 
IBMBPEV - ABEND analyzer 112 
IBMBPGD 8 2 

IBMBPGO, interpretive GOTO 30 
IBMBPGR, storage management 79-82Z 
IBMBPII 6 8 
IBMBPIR 6 8 
IBMBPSL 44 
IBMBPSM 44 
IBMBPSR 44 

IBMBRAA regional seq output trans 126 
IBMBRAB regional seq output trans 126 
IBMBRAC regional seq output trans 126 
IBMBRAD regional seq output trans 126 
IBMBRAE regional seq output trans 126 
IBMBRAF regional seq output trans 126 
IBMBRAG regional seq output trans 126 
IBMBRAH regional seq output trans 126 
IBMBRAI regional seq output trans 126 
IBMBRBA regional seq in/upd trans 126 
IBMBRBC regional seq in/upd trans 126 
IBMBRBD regional seq in/upd trans 126 
IBMBRBE regional seq in/upd trans 126 
IBMBRBF regional seq in/upd trans 126 
IBMBRBG regional seq in/upd trans 126 
IBMBRCA unbuffered consec trans 126 
IBMBRCB unbuffered consec trans 126 
IBMBRCC unbuffered consec trans 126 
IBMBRDA regional direct non-exc trans 126 
IBMBRDB regional direct non-exc trans 126 
IBMBRDC regional direct non-exc trans 126 
IBMBRDD regional direct non-exc trans 126 
IBMBREA record I/O error module 126 
IBMBREB record I/O error module 126 
IBMBRteC record I/O error module 126 
IBMBREF ENDFILE module 126 
IBMBRIO record I/O interface 126 
description of functions 126 
parameter list 130 
IBMBRJA indexed seq in/upd trans 126 
IBMBRJB indexed seq in/upd trans 126 
IBMBRKA indexed direct no-exc trans 126 
IBMBRKA indexed direct non-exc trans 126 
IBMBRKB indexed direct non-exc trans 126 
IBMBRKC indexed direct non-exc trans 126 
IBMBRLA indexed direct non-exc trans 126 
IBMBRLB indexed direct non-exc trans 126 
IBMBRQA buffered consec non-spanned 

trans 126 
IBMBRQB buffered consec non-spanned 

trans 126 
IBMBRQD buffered consec non-spanned 

trans 126 
IBMBRQE buffered consec input spanned 

trans 126 
IBMBRQF buffered consec output spanned 

trans 126 
IBMBRQG buffered consec update spanned 

trans 126 
IBMBRTP teleprocessing input trans 126 



IBMBRXA exc regional direct upd/input 

trans 126 
IBMBRXB exc regional direct upd/input 

trans 126 
IBMBRXC exc regional direct upd/input 

trans 126 
IBMBRXD exc regional direct upd/input 

trans 126 
IBMBRYA exc indexed direct upd/input 

trans 126 
IBMBRYB exc indexed direct upd/input 

trans 126 
IBMBRYB exc indexed upd/input trans 126 
IBMBRYC exc indexed direct upd/input 

trans 126 
IBMBRYD exc indexed direct upd/input 

trans 126 
IBMBSAI 180 
IBMBSAO 180 
IBMBSCI 180 
IBMBSCO 180 

IBMBSCP, COPY module 175,180 
IBMBSCV 180 
IBMBSDI 179-180 
IBMBSDO 179-180 
IBMBSED 179-180 
IBMBSEI 179-180 
IBMBSEO 179-180 
IBMBSFI 180 
IBMBSFO 180 
IBMBSIC 177 
IBMBSII 179 
IBMBSIO 179 
IBMBSIS 180 
IBMBSLI 179-180 
IBMBSLO 179-180 
IBMBSOC 177 
IBMBSOF stream output file 

trans 12 6,179-180 
IBMBSOU stream output file 

trans 12 6,179-180 
IBMBSOV 179-180 
IBMBSPC 177,180 
IBMBSPI 180 
IBMBSPL 179-180 
IBMBSPO 180 
IBMBSTAB 171 
IBMBSTF Stream output print file 

trans 126,179-180 
IBMBSTI stream input trans 126,179-180 
IBMBSTU stream output print file 

trans 126,180 
IBMBSTV stream output print file 

trans 126,179-180 
IBMBSXC 180 

IBMTJWT wait module multitasking 269 
IBMTPIR 260 
IBMTPSL 4 4 
IBMTPSR 44 

lELCGBB, test for '1* bits 34 
lELCGBO, test for 'O' bits 33 
lELCGCB, compare long bit 33 
lELCGCL, compare long 33 
lELCGIA, stream input 33 
lELCGIB,, stream input 33 
lELCGMV, move long 33 
lELCGOA, stream output 33 
lELCGOB, stream output 33 
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lELCGOC, stream I/O X format items 33,171 
lELCGON, dynamic ONCB chaining 33 
lELCGRV, revert 7DA chaining 33 
implicit close in record I/O 143,127 
implicit open 

record I/O 127,144 

stream I/O 156 
in-line conversion 183-185 

example of 18 6 

list of fundamental types 185 
in-line record I/O 14 6 
INDEX built-in function 191 
indexing interleaved arrays 190 
initial storage area (ISA) 8,68,75,75-78 
initialization 

FORTRAN 238 

PL/I 6 5-69 

program 65-69 

stream I/O subroutines 178 
input/output control block (lOCB) 301 
instruction, associating with module 218 
INTER option 242 
interlanguage communication 231-253 

aggregate arguments 231-252,250 

arrays 250,233 

ASSEMBLER option 251 

basic rules 231 

COBOL option of ENV attribute 251 

control blocks 238 

FORTRAN calls PL/I 248 

IBMBILCl 238 

interrupt handling 247,24 9 

interrupt in COBOL 246 

interrupt in FORTRAN 247 

interrupt in PL/I 249 

NOMAP option 250 

NOMAPIN option 250 

NOMAPOUT option 25 

PL/I calls COBOL 242 

PL/I calls FORTRAN 246 

principles 233 

storage 250 

structures 250 

use of locators 233 

VDA 238 

ZCTL 238 
interlanguage root control block 

IBMBILCl) 298 
interlanguage VDA 299 
internal form of data types 181 
interpretive code, need for 
interpretive GOTO routine IBMBPGO 30 
interrupt control block (ICB) 300 
interrupt handling 87-121 

COBOL 246 

event I/O 143 

FORTRAN 247 

library subroutine IBMBERR 102-106 

return from 104 
interrupt identification using 
dump 205-228 

in library module 224 

interrupt address 215 
invert-aligned- bit-string subroutine 

(IBMBBBN) 191 
lOCB (input/output control block) 301 
ISA (initial storage area) 68,75 

multitasking 85 



KEY condition 88 
key descriptor (KD) 
key variable 135 



130,304 



label data format 305 
label variables 

errors when using 30 

format 305 

general description 29 
last free area (TLFE) 71 
last-in/first-out (LIFO) storage 75-80 
library calls 32 

addressing 32 

example of calling sequences 32 

general 30 

mnemonic letter usage 32 

within TCA 32 
library subroutines 31-32 

arithmetic 18 9 

array handling 189-191 

computational 189 

conversion package 181 

in record I/O 126 

in stream I/O 179 

mathematical 189 

naming conventions 32 

string handling 18 9 

workspace 42 
library workspace (LWS) 

description 42 

format and function 306 
LIFO (last-in/first-out) storage 75-79 
LINE format option 171 
link-editing 65 
list-directed I/O 160 
listing conventions 15 
load module 

entry point 11 
LOCATE statement 125,130-132 
locators 53-60 

aggregate locator format and 
function 275 

area locator/descriptor format and 
function 272 

string locator/descriptor format and 
function 318 
logical operation subroutines 191 



main procedure 

no main procedure 65 

termination 6 9 
major free area 76 
modification of do-loop control 38 
module, object 11 

movement of expressions out of loops 34 
multiple conversion 188 
multitasking 255-270 

completion values 268 

following chaining in dump 225 

housekeeping 256 

ISA acquiring 85 

library 260 

POSTCODES 256 

priority 256 

reading dumps, general 228 

TCA tasking appendage (TTA) 256,326 
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multitasking (continued) 
WAIT statement 268 

NAB (next available byte) pointer 76 

NAME condition 174,88 

naming of library modules 32 

next available byte (NAB) pointer 76 

NOCHECK prefix 105,106 

NOCONVERSION prefix 188 

NOMAP option 250 

NOMAPIN option 250 

NOMAPOUT option 250 

non-LIFO storage 76,79 

NOSPIE option 68 

NOSTAE option 68 

null on-unit 102 

NULL values 21 



object module 11 

object program listing, contents 15 

object program listing, example 14 

OCB see open control block 

OCCURS (COBOL) 2 50 

ODL (ordered delete list) 310 

OEE (offset to end of extent) 85 

offsets null value 21 

ON CHECK 106 

ON communications area (ONCA) 

chain in dump 223 

description 97 

dummy 97 

format and function 307 
ON control block (ONCB) 

description 100 

format and function 308 
ON statement 100-102 
on-cells 102 
on-code 97 
on- units 30,102 

GOTO only 30 
ONCA 72,3 07 

ONCHAR function/pseudovariable 17 U 
ONSOURCE function/pseudovariable 174 
open control block (OCB) 

format 3 09 

function 128 
OPEN statement 128 
opening files 

explicit open for record I/O 128,125 

implicit open for record I/O 127,143 
operating system interfaces 

miscellaneous 191-203 

see also I/O; error handling; 
initialization 
operation interrupt 88 
optimization 

branching around redundant 
expressions 37 

commoning constants and control 
blocks 36 

effect on conversions 181 

elimination of common expression 34 

elimination of unreachable 
statements 3 6 

examples of 33-38 

general 33-38 



optimization (continued) 

modification of do- loop control 38 
movement of expressions out of loops 34 
rationalization of branches 36 

OR logical operation 191 

ordered delete list (ODL) 310 

output, compiler 11-38 

overflow routine, IBMBPGR 79,71 



packed intermediate decimal format 181 
PAGE format option 171 
parameter lists 30 

contents in dump 227 
PICTURE data 

DEDs 2 80 

FEDS 280 
PL/I - ASSEMBLER communication 251 
PL/I-COBOL communication 231-253 
PL/I-FORTRAN communication 231-253 
PLIBASE 2 55 
PLICALLA 68 
PLICALLB 68 
PLICKPT 197 
PLICOUNT 120 
PLIDUMP facility 

how to use 207,215 

implementation 109 
PLIFLOW 11,120 
PLIMAIN 65 

format 311 
PLISORT 192,197 
PLISTART 65,11 
PLITABS 171 
PLITASK 255 
PLIXOPT 6 8 
pointers 

BOS 76 

COPY option 175 

EOS 76 

NAB 76 

storage handling 76 
pointers, null value 21 
POLY built-in function 191 
POST ECB 256 
POSTCODES list of 256 
PRINT files 171 
priority of task 256 
privileged operation interrupt 88 
program check interrupts 96 
program control data 22 

DED 27 8-281 
program control section 11 

contents 18 
program management area 69-71 
prologue 24 

example 24 
prompting 177-17 8 
protection interrupt 88 
pseudo register vector 

general description 21 

initialization 22 

location of 22 
purge task subroutine 266 
PUT statement 160 



qualified conditions 87 
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READ Statement 130-132,125 
recompilation to obtain dump, avoiding 
RECORD condition 88 
record descriptor (RD) 135,312 
record I/O 125-151 

control blocks generated 128 

error handling 144 

in line 146 

interface routine (IBMBRIO) 130 

library routines 126 

library-call 125 

VSAM data sets 130 
record variable 135 

redundant expressions, branching around 
REFER option 54-56,191 
register usage 17 

branch and link 18 

compiled code 18 

DO loop control 19 

preferred registers 19 

static backchain 19 
registers 19 

even/odd pairs 19 

floating point 19 

library usage 19 

work 19 
relative virtual origin (RVO) 53,54-56 
REPEAT built-in function 191 
REPLY option 192 
report table 82 
request control block (RGB) 

description 130 

format and function 313 
RETURN statement 27 



save areas 

IBMBPGR 71 

IBMBPIR 71 

registers in dump 
SAVE field in SIOCB 
SCNT field in SIOCB 
SFCB field in SIOCB 
SFLG field in SIOCB 
shared library 4 4-50 

initialization 50 

link pack area 48 

multitasking 50 

region 4 8 
SIGNAL statement 96 
significance interrupt 
SIZE condition 88,103 
SKIP format option 171 
SLD (string locator/descriptor) 

subroutine 191 
SOCA field in SIOCB 
software interrupts 

definition 87 

main discussion 
SORT exit 197 
sort/merge facility 192 
source definition 146 
specification interrupt 
squashed mode 17 8 
SRTN field in SIOCB 
SSDD field in SIOCB 
SSRC field in SIOCB 
SSTR field in SIOCB 



220 
156 
156 
156 
156 



96 



156 



103-105 



156 
156 
156 
156 
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standard save area, operating system 75 
209 statement frequency count table 

discussion 120 

format and function 314 
statement number 

in messages 107 

of error, in dump 221 
statement number table (SNT or DST) 315 

location in dump 227 
static backchain 26 

in dump 224 
static control sections 15 
static descendency 87 
37 static internal control section 15 
static ONCBs 100 
static storage map 15 

example 13 
static variables 21 

locating in dump 226 
STATUS function/pseudovariable 197 
STDD field in SIOCB 156 
storage 

initial storage area (ISA) 68 

main discussion 75-85 

routine IBMBPGR 77-82 

segments 76,7 9 
storage report table 

format 316 
storage reports 82-85 

implementation 82-85 

information given 82 

multitasking 84 
stream I/O 146 

built-in functions 174 

conditions 17 4-176 

COPY option 175 

COUNT function 174 

DATAFIELD function 174 

director routines 179 

end of file 174 

external conversion director 
modules 180 

file opening 156 

format items 16 9 

format lists 171 

formatting modules 180 

implicit open 156 

initializing modules 179 

ONCHAR function/pseudovariable 174 

ONSOURCE function/pseudovariable 174 

transmitter modules 179-180 
stream I/O control block (SIOCB) 156,317 
STRG field in SIOCB 156 
strings 

adjustable 18 9 

built in functions 189,191 

DED 27 8 

descriptor 318 

FED 281 

length 54-56 

locator/descriptor 54-56,318 

STRING function/pseudovariable 191 

STRING option 175 

STRINGRANGE condition 90 

STRINGSIZE condition 90,189 
structures 

assignments 23 

COBOL 250 
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structures (continued) 

descriptor 54-56,319 

element (definition) 53 

implementation of 23 

interlanguage coimnunication 250,233 

mapping 250,54-56 

of arrays 54-56 
structures of arrays 23 
subroutines, compiler-generated 180 
SUBSCRIPTRANGE condition 90 
SUBSTR built-in function 191 
SUM built-in function 191 
symbol table (SYMTAB) 

format 320 

general 61 
symbol table element list see symbol table 

vector 
symbol table vector 61 

format 322 
SYMTAB see symbol table 
system action, standard 

definition 87 
system detected interrupts 96 



tab table 171 

target, definition 146 

task communications area (TCA) 

appendage (TIA) 71,325 

description 69-71 

format 323 

tasking appendage (tTA) 256,326 
task variable 

format and function 327 
tasking appendage (TTA) 256,326 
TCA see task communications area 
temporaries 20 
temporary variables (temporaries) 20 

storage 75 
termination of program 69 
TIA (TCA implementation appendage) 71,325 
TIME built-in function 191 
trace 

FLOW option 114 

following through dump 219 

information in dump 210 
transfer vector 44 
transient library 40-50 
TRANSLATE built-in function 191 
transmission statement 

in record I/O 125,130 
TRANSMIT condition 145 

detecting 96 
transmitter modules 

record I/O 12 6 

stream I/O 179-180 
TSO (time sharing option) 177-178 
TTA (TCA tasking appendage) 

format 326 

general 256-2 58 
TXT records 11 



user exits 192 



variable data area (VDA) 

interlanguage communication 238,299 
variables 20 

AUTOMATIC 19 

BASED 20 

CONTROLLED 20 

entry 287 

EXTERNAL 65 

label 305 

locating in dump 226-228 

pointer 21 

STATIC 21 

temporaries 2 
varying-length strings 

internal representation 181 
VERIFY built-in function 191 
VSAM data sets 130 

opening 130 



WAIT ECB 256 

wait event table (WIT) 268,328 
WAIT macro instruction 192 
WAIT statement 

multitasking 268 

non-multitasking 198 
weak external reference (WXTRN) 44 
WIT (wait event table) 268,328 
WRITE statement 130-132,125 
WXTRN (weak external reference) 44 



X format items 171,18 

XBF (exclusive file block) 292 

XBI (exclusive block lOCB) 291 



ZCTL (zygo-lingual control list) 238,329 

ZERODIVIDE condition 88 

zygo-lingual control list (ZCTL) 238,329 



unaligned bit strings 181 
UNDEFINEDFILE condition 88 
UNDERFLOW condition 88 
unqualified conditions 87 
use of locators 233 
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